replace-in-file

What is replace-in-file?

The replace-in-file npm package allows you to easily search and replace text in files. It is useful for tasks such as updating configuration files, modifying source code, and performing batch text replacements.

What are replace-in-file's main functionalities?

Basic Replacement

This feature allows you to perform a basic search and replace operation in a specified file. The 'from' field can be a string or a regular expression, and the 'to' field is the replacement string.

const replace = require('replace-in-file');

const options = {
  files: 'path/to/file.txt',
  from: /oldText/g,
  to: 'newText',
};

replace(options)
  .then(results => console.log('Replacement results:', results))
  .catch(error => console.error('Error occurred:', error));

Multiple Replacements

This feature allows you to perform multiple search and replace operations in a single file. The 'from' and 'to' fields are arrays, where each element in 'from' is replaced by the corresponding element in 'to'.

const replace = require('replace-in-file');

const options = {
  files: 'path/to/file.txt',
  from: [/oldText1/g, /oldText2/g],
  to: ['newText1', 'newText2'],
};

replace(options)
  .then(results => console.log('Replacement results:', results))
  .catch(error => console.error('Error occurred:', error));

Glob Pattern Matching

This feature allows you to use glob patterns to specify multiple files for the search and replace operation. This is useful for batch processing multiple files in a directory.

const replace = require('replace-in-file');

const options = {
  files: 'path/to/*.txt',
  from: /oldText/g,
  to: 'newText',
};

replace(options)
  .then(results => console.log('Replacement results:', results))
  .catch(error => console.error('Error occurred:', error));

Dry Run

This feature allows you to perform a dry run of the search and replace operation. No actual changes are made to the files, but you can see what the results would be. This is useful for testing your replacement logic before applying it.

const replace = require('replace-in-file');

const options = {
  files: 'path/to/file.txt',
  from: /oldText/g,
  to: 'newText',
  dry: true,
};

replace(options)
  .then(results => console.log('Dry run results:', results))
  .catch(error => console.error('Error occurred:', error));

Other packages similar to replace-in-file

replace

The 'replace' package is another tool for performing search and replace operations in files. It offers similar functionality to 'replace-in-file' but with a simpler API. It is suitable for straightforward replacement tasks.

string-replace-loader

The 'string-replace-loader' package is a webpack loader that allows you to perform string replacements in your source files during the build process. It is useful for replacing text in JavaScript and other files as part of your build pipeline.

gulp-replace

The 'gulp-replace' package is a plugin for the Gulp task runner that allows you to perform search and replace operations in your Gulp streams. It integrates well with Gulp workflows and is useful for automating text replacements in your build process.

README

Replace in file

A simple utility to quickly replace text in one or more files or globs. Works synchronously or asynchronously with either promises or callbacks. Make a single replacement or multiple replacements at once.

Installation

# Using npm
npm install replace-in-file

# Using yarn
yarn add replace-in-file

Usage

Specify options

const replace = require('replace-in-file');
const options = {

  //Single file or glob
  files: 'path/to/file',

  //Multiple files or globs
  files: [
    'path/to/file',
    'path/to/other/file',
    'path/to/files/*.html',
    'another/**/*.path',
  ],

  //Replacement to make (string or regex)
  from: /foo/g,
  to: 'bar',

  //Multiple replacements with the same string (replaced sequentially)
  from: [/foo/g, /baz/g],
  to: 'bar',

  //Multiple replacements with different strings (replaced sequentially)
  from: [/foo/g, /baz/g],
  to: ['bar', 'bax'],

  //Specify if empty/invalid file paths are allowed (defaults to false)
  //If set to true these paths will fail silently and no error will be thrown.
  allowEmptyPaths: false,

  //Character encoding for reading/writing files (defaults to utf-8)
  encoding: 'utf8',

  //Single file or glob to ignore
  ignore: 'path/to/ignored/file',

  //Multiple files or globs to ignore
  ignore: [
    'path/to/ignored/file',
    'path/to/other/ignored_file',
    'path/to/ignored_files/*.html',
    'another/**/*.ignore',
  ]
};

Replacing multiple occurrences

Please note that the value specified in the from parameter is passed straight to the native String replace method. As such, if you pass a string as the from parameter, it will only replace the first occurrence.

To replace multiple occurrences at once, you must use a regular expression for the from parameter with the global flag enabled, e.g. /foo/g.

Asynchronous replacement with promises

replace(options)
  .then(changedFiles => {
    console.log('Modified files:', changedFiles.join(', '));
  })
  .catch(error => {
    console.error('Error occurred:', error);
  });

Asynchronous replacement with callback

replace(options, (error, changedFiles) => {
  if (error) {
    return console.error('Error occurred:', error);
  }
  console.log('Modified files:', changedFiles.join(', '));
});

Synchronous replacement

try {
  const changedFiles = replace.sync(options);
  console.log('Modified files:', changedFiles.join(', '));
}
catch (error) {
  console.error('Error occurred:', error);
}

Return value

The return value of the library is an array of file names of files that were modified (e.g. had some of the contents replaced). If no replacements were made, the return array will be empty.

For example:

const changedFiles = replace.sync({
  files: 'path/to/files/*.html',
  from: 'a',
  to: 'b',
});

// changedFiles could be an array like:
[
  'path/to/files/file1.html',
  'path/to/files/file3.html',
  'path/to/files/file5.html',
]

CLI usage

replace-in-file from to some/file.js,some/**/glob.js
  [--ignore=ignore/files.js,ignore/**/glob.js]
  [--encoding=utf-8]
  [--allowEmptyPaths]
  [--isRegex]
  [--verbose]

The flags allowEmptyPaths, ignore and encoding are supported in the CLI. In addition, the CLI supports the verbose flag to list the changed files.

Multiple files or globs can be replaced by providing a comma separated list.

A regular expression may be used for the from parameter by specifying the --isRegex flag.

License

(MIT License)

Copyright 2015-2017, Adam Reis