Add dry run option

Fixes #1

Author: sindresorhus

api.d.ts

@@ -1,9 +1,16 @@
+export type FileChange = {
+	filePath: string;
+	originalContent: string;
+	newContent: string;
+};
+
 export default function replaceInFiles(
 	path: string | string[],
 	options: {
 		find: Array<string | RegExp>;
 		replacement: string;
 		ignoreCase?: boolean;
 		glob?: boolean;
+		dryRun?: boolean;
 	},
-): Promise<void>;
+): Promise<void | FileChange[]>;

api.js

@@ -11,7 +11,7 @@ const normalizePath = process.platform === 'win32' ? normalizePath_ : x => x;
 // TODO(sindresorhus): I will extract this to a separate module at some point when it's more mature.
 // `find` is expected to be `Array<string | RegExp>`
 // The `ignoreCase` option overrides the `i` flag for regexes in `find`
-export default async function replaceInFiler(filePaths, {find, replacement, ignoreCase, glob} = {}) {
+export default async function replaceInFiler(filePaths, {find, replacement, ignoreCase, glob, dryRun} = {}) {
 	filePaths = [filePaths].flat();
 
 	if (filePaths.length === 0) {
@@ -45,6 +45,8 @@ export default async function replaceInFiler(filePaths, {find, replacement, igno
 		return new RegExp(element.source, `${element.flags.replace('i', '')}${iFlag}`);
 	});
 
+	const changes = [];
+
 	await Promise.all(filePaths.map(async filePath => {
 		const string = await fsPromises.readFile(filePath, 'utf8');
 
@@ -57,6 +59,18 @@ export default async function replaceInFiler(filePaths, {find, replacement, igno
 			return;
 		}
 
-		await writeFileAtomic(filePath, newString);
+		if (dryRun) {
+			changes.push({
+				filePath,
+				originalContent: string,
+				newContent: newString,
+			});
+		} else {
+			await writeFileAtomic(filePath, newString);
+		}
 	}));
+
+	if (dryRun) {
+		return changes;
+	}
 }

cli.js

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 import process from 'node:process';
+import {styleText} from 'node:util';
 import meow from 'meow';
 import replaceInFiles from './api.js';
 
@@ -13,11 +14,13 @@ const cli = meow(`
 	  --replacement     Replacement string  (Required)
 	  --ignore-case     Search case-insensitively
 	  --no-glob         Disable globbing
+	  --dry-run         Show what would be replaced without making changes
 
 	Examples
 	  $ replace-in-files --string='horse' --regex='unicorn|rainbow' --replacement='🦄' foo.md
 	  $ replace-in-files --regex='v\\d+\\.\\d+\\.\\d+' --replacement=v$npm_package_version foo.css
 	  $ replace-in-files --string='blob' --replacement='blog' 'some/**/[gb]lob/*' '!some/glob/foo'
+	  $ replace-in-files --dry-run --string='old' --replacement='new' file.txt
 
 	You can use the same replacement patterns as with \`String#replace()\`, like \`$&\`.
 `, {
@@ -43,6 +46,10 @@ const cli = meow(`
 			type: 'boolean',
 			default: true,
 		},
+		dryRun: {
+			type: 'boolean',
+			default: false,
+		},
 	},
 });
 
@@ -56,12 +63,64 @@ if (!cli.flags.regex && !cli.flags.string) {
 	process.exit(1);
 }
 
-await replaceInFiles(cli.input, {
+function displayDryRunResults(changes) {
+	if (changes.length === 0) {
+		console.log('No matches found.');
+		return;
+	}
+
+	for (const change of changes) {
+		console.log(`\n${styleText('magenta', change.filePath)}`);
+
+		const lines = change.originalContent.split('\n');
+		const newLines = change.newContent.split('\n');
+
+		for (const [index, line] of lines.entries()) {
+			if (line !== newLines[index]) {
+				const lineNumber = index + 1;
+				const linePrefix = styleText('cyan', `${lineNumber}:`);
+
+				console.log(`${linePrefix}${highlightDifferences(line, newLines[index], 'red')}`);
+				console.log(`${linePrefix}${highlightDifferences(newLines[index], line, 'green')}`);
+			}
+		}
+	}
+}
+
+function highlightDifferences(text, otherText, color) {
+	let start = 0;
+	let end = text.length;
+	let otherEnd = otherText.length;
+
+	// Find common prefix
+	while (start < Math.min(text.length, otherText.length) && text[start] === otherText[start]) {
+		start++;
+	}
+
+	// Find common suffix
+	while (end > start && otherEnd > start && text[end - 1] === otherText[otherEnd - 1]) {
+		end--;
+		otherEnd--;
+	}
+
+	if (start >= end) {
+		return text;
+	}
+
+	return text.slice(0, start) + styleText(color, text.slice(start, end)) + text.slice(end);
+}
+
+const result = await replaceInFiles(cli.input, {
 	find: [
 		...cli.flags.string,
 		...cli.flags.regex.map(regexString => new RegExp(regexString, 'g')),
 	],
 	replacement: cli.flags.replacement,
 	ignoreCase: cli.flags.ignoreCase,
 	glob: cli.flags.glob,
+	dryRun: cli.flags.dryRun,
 });
+
+if (cli.flags.dryRun) {
+	displayDryRunResults(result);
+}

readme.md

@@ -22,11 +22,13 @@ $ replace-in-files --help
     --replacement     Replacement string  (Required)
     --ignore-case     Search case-insensitively
     --no-glob         Disable globbing
+    --dry-run         Show what would be replaced without making changes
 
   Examples
     $ replace-in-files --string='horse' --regex='unicorn|rainbow' --replacement='🦄' foo.md
     $ replace-in-files --regex='v\d+\.\d+\.\d+' --replacement=v$npm_package_version foo.css
     $ replace-in-files --string='blob' --replacement='blog' 'some/**/[gb]lob/*' '!some/glob/foo'
+    $ replace-in-files --dry-run --string='old' --replacement='new' file.txt
 
   You can use the same replacement patterns as with `String#replace()`, like `$&`.
 ```

test.js

@@ -63,3 +63,30 @@ test('no globs', async t => {
 		},
 	);
 });
+
+test('--dry-run shows changes without modifying files', async t => {
+	const filePath = await tempWrite('foo bar foo');
+	const {stdout} = await execa('./cli.js', ['--dry-run', '--string=bar', '--replacement=baz', filePath]);
+
+	t.is(fs.readFileSync(filePath, 'utf8'), 'foo bar foo');
+	t.true(stdout.includes(filePath));
+	t.true(stdout.includes('foo bar foo'));
+	t.true(stdout.includes('foo baz foo'));
+});
+
+test('--dry-run with no matches', async t => {
+	const filePath = await tempWrite('foo bar foo');
+	const {stdout} = await execa('./cli.js', ['--dry-run', '--string=notfound', '--replacement=replacement', filePath]);
+
+	t.is(fs.readFileSync(filePath, 'utf8'), 'foo bar foo');
+	t.is(stdout.trim(), 'No matches found.');
+});
+
+test('--dry-run with regex', async t => {
+	const filePath = await tempWrite('version 1.2.3 here');
+	const {stdout} = await execa('./cli.js', ['--dry-run', '--regex=\\d+\\.\\d+\\.\\d+', '--replacement=2.0.0', filePath]);
+
+	t.is(fs.readFileSync(filePath, 'utf8'), 'version 1.2.3 here');
+	t.true(stdout.includes('version 1.2.3 here'));
+	t.true(stdout.includes('version 2.0.0 here'));
+});