Command Line Search and Replace Utility

1.2.2 · active · verified Sun Apr 19

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.

Common errors

```
Invalid switch - -h No files replaced
```
cause The system is executing the Windows built-in `replace` command instead of the globally installed Node.js `replace` utility.

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.

Warnings

gotcha 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'.
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`.
gotcha 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.
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.
gotcha 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`).
Fix: Familiarize yourself with JavaScript's `RegExp` and `String.prototype.replace()` documentation, especially regarding capture groups (`$1`, `$2`, etc.) and special characters.

Install

npm install replace npm
yarn add replace yarn
pnpm add replace pnpm

Imports

replace
wrong:
```
import replace from 'replace';
```
correct:
```
const replace = require('replace');
```
The programmatic API for 'replace' is CommonJS-only and exposes a single function. This package does not provide ESM exports.

Quickstart

Demonstrates programmatic search and replace within a specified directory using JavaScript regular expression syntax.

const replace = require('replace');

// Example: Replace 'old_text' with 'new_text' in all .js files in a specific directory recursively
replace({
  regex: 'old_text',
  replacement: 'new_text',
  paths: ['./my-project-folder/'], // Specify the directory or files to search
  recursive: true,
  silent: false, // Set to true to suppress console output
  // You can also add includes/excludes like:
  // include: '*.js',
  // exclude: '*.min.js'
});

console.log('Replacement process initiated.');
// Note: replace is asynchronous but doesn't return a Promise or take a callback directly for completion. 
// For robust programmatic use, consider wrapping it in a Promise or handling file system events if precise timing is needed.

view raw JSON →