{"id":14891,"library":"replace","title":"Command Line Search and Replace Utility","description":"The `replace` utility is a command-line tool for performing search-and-replace operations across multiple files. It functions similarly to `sed` but distinguishes itself by directly modifying files when matches are found, offering recursive directory search capabilities, and leveraging JavaScript syntax for regular expressions and replacement strings. Additionally, it provides a `search` command that mimics `grep`'s functionality, utilizing the same JS-based regex patterns. The current stable version is 1.2.2. While its release cadence isn't explicitly defined, the version number suggests a mature, stable tool with infrequent updates. Its key differentiators include its direct file modification approach, ease of recursive operations, and the familiarity of JavaScript regex for developers. It also offers a programmatic API for integration into Node.js applications and includes default and customizable file exclusion patterns.","status":"active","version":"1.2.2","language":"javascript","source_language":"en","source_url":"https://github.com/ALMaclaine/replace","tags":["javascript","sed","grep","search","replace"],"install":[{"cmd":"npm install replace","lang":"bash","label":"npm"},{"cmd":"yarn add replace","lang":"bash","label":"yarn"},{"cmd":"pnpm add replace","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The programmatic API for 'replace' is CommonJS-only and exposes a single function. This package does not provide ESM exports.","wrong":"import replace from 'replace';","symbol":"replace","correct":"const replace = require('replace');"}],"quickstart":{"code":"const replace = require('replace');\n\n// Example: Replace 'old_text' with 'new_text' in all .js files in a specific directory recursively\nreplace({\n  regex: 'old_text',\n  replacement: 'new_text',\n  paths: ['./my-project-folder/'], // Specify the directory or files to search\n  recursive: true,\n  silent: false, // Set to true to suppress console output\n  // You can also add includes/excludes like:\n  // include: '*.js',\n  // exclude: '*.min.js'\n});\n\nconsole.log('Replacement process initiated.');\n// Note: replace is asynchronous but doesn't return a Promise or take a callback directly for completion. \n// For robust programmatic use, consider wrapping it in a Promise or handling file system events if precise timing is needed.","lang":"javascript","description":"Demonstrates programmatic search and replace within a specified directory using JavaScript regular expression syntax."},"warnings":[{"fix":"Ensure that npm's global binaries directory is prioritized in your system's PATH environment variable, or invoke the utility explicitly via `npx replace` or `node $(npm root -g)/replace/bin/replace`.","message":"On Windows, the globally installed `replace` command-line utility can conflict with the built-in Windows `replace` command, leading to errors like 'Invalid switch - -h'.","severity":"gotcha","affected_versions":"All versions on Windows"},{"fix":"Use the quiet flag (`-q`), include only necessary file types with `--include=\"*.js\"`, or limit lines shown in preview with `-n` to improve performance.","message":"When processing very large directories, the `replace` utility might take a significant amount of time or consume substantial resources. This is particularly true for preview modes or extensive recursive searches.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Familiarize yourself with JavaScript's `RegExp` and `String.prototype.replace()` documentation, especially regarding capture groups (`$1`, `$2`, etc.) and special characters.","message":"The `replace` utility uses JavaScript regular expression syntax and replacement string rules, which may differ from `sed` or `grep` for users accustomed to those tools' specific syntaxes (e.g., capture group syntax like `$1` vs `\\1`).","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Adjust your system's PATH environment variable to prioritize npm's global binaries, or use `npx replace` to ensure the correct executable is run.","cause":"The system is executing the Windows built-in `replace` command instead of the globally installed Node.js `replace` utility.","error":"Invalid switch - -h No files replaced"}],"ecosystem":"npm"}