{"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,"search_vec":"'1.2.2':81 'across':23 'addit':57 'also':123 'api':127 'applic':132 'approach':109 'base':73 'cadenc':85 'capabl':46 'command':1,13,62 'command-lin':12 'current':77 'customiz':137 'default':135 'defin':89 'develop':121 'differenti':103 'direct':35,106 'directori':44 'distinguish':32 'eas':110 'exclus':139 'explicit':88 'express':53 'familiar':116 'file':25,37,107,138 'found':41 'function':27,67 'grep':65,143 'includ':104,134 'infrequ':99 'integr':129 'isn':86 'javascript':49,118,141 'js':72 'js-base':71 'key':102 'leverag':48 'line':2,14 'match':39 'matur':95 'mimic':64 'modif':108 'modifi':36 'multipl':24 'node.js':131 'number':92 'offer':42,124 'oper':22,113 'pattern':75,140 'perform':17 'programmat':126 'provid':59 'recurs':43,112 'regex':74,119 'regular':52 'releas':84 'replac':5,8,21,55,145 'search':3,19,45,61,144 'search-and-replac':18 'sed':30,142 'similar':28 'stabl':78,96 'string':56 'suggest':93 'syntax':50 'tool':15,97 'updat':100 'util':6,9,68 'version':79,91","created_at":"2026-04-20T18:44:09.694752+00:00","updated_at":"2026-04-20T18:44:09.694752+00:00","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","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"2020.12.3","cli_name":"replace","cli_version":null,"type":"library","homepage":"https://marketplace.visualstudio.com/items?itemName=donjayamanne.replacer","github":"https://github.com/ALMaclaine/replace","docs":null,"changelog":null,"pypi":null,"npm":"https://www.npmjs.com/package/replace","openapi_spec":null,"status_page":null,"smithery":null,"categories":["devops"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-17","next_check":"2026-07-18","install_tag":null}}