Add --dry-run as an alias of --preview

It’s actually the other way around, but it’s easier to explain it as an alias since the change is backwards compatible.

Fixes #783

Author: sindresorhus

readme.md

@@ -23,7 +23,7 @@
   <sub>(does not apply to external registries)</sub>
 - Opens a prefilled GitHub Releases draft after publish
 - Warns about the possibility of extraneous files being published
-- See exactly what will be executed with [preview mode](https://github.com/sindresorhus/np/issues/391), without pushing or publishing anything remotely
+- See exactly what will be executed with [dry-run mode](https://github.com/sindresorhus/np/issues/391), without pushing or publishing anything remotely
 - Supports [GitHub Packages](https://github.com/features/packages)
 - Supports npm 9+, Yarn (Classic and Berry), pnpm 8+, and Bun
 
@@ -62,7 +62,7 @@ $ np --help
     --no-tests              Skips tests
     --yolo                  Skips cleanup and testing
     --no-publish            Skips publishing
-    --preview               Show tasks without actually executing them
+    --dry-run               Show tasks without actually executing them
     --tag                   Publish under a given dist-tag
     --contents              Subdirectory to publish
     --no-release-draft      Skips opening a GitHub release draft
@@ -101,7 +101,7 @@ Currently, these are the flags you can configure:
 - `tests` - Run `npm test` (`true` by default).
 - `yolo` - Skip cleanup and testing (`false` by default).
 - `publish` - Publish (`true` by default).
-- `preview` - Show tasks without actually executing them (`false` by default).
+- `dryRun` - Show tasks without actually executing them (`false` by default). The CLI also accepts `--preview` as an alias.
 - `tag` - Publish under a given dist-tag (`latest` by default).
 - `contents` - Subdirectory to publish (`.` by default).
 - `releaseDraft` - Open a GitHub release draft after releasing (`true` by default).

source/cli-implementation.js

@@ -32,7 +32,7 @@ const cli = meow(`
 	  --no-tests             Skips tests
 	  --yolo                 Skips cleanup and testing
 	  --no-publish           Skips publishing
-	  --preview              Show tasks without actually executing them
+	  --dry-run              Show tasks without actually executing them
 	  --tag                  Publish under a given dist-tag
 	  --contents             Subdirectory to publish
 	  --no-release-draft     Skips opening a GitHub release draft
@@ -54,6 +54,7 @@ const cli = meow(`
 `, {
 	importMeta: import.meta,
 	booleanDefault: undefined,
+	allowUnknownFlags: false,
 	// Don't use `default` for flags - we apply defaults later so config can override them
 	flags: {
 		anyBranch: {
@@ -92,8 +93,9 @@ const cli = meow(`
 		contents: {
 			type: 'string',
 		},
-		preview: {
+		dryRun: {
 			type: 'boolean',
+			aliases: ['preview'],
 		},
 		testScript: {
 			type: 'string',
@@ -133,7 +135,7 @@ async function getOptions() {
 	const explicitCliFlags = Object.fromEntries(Object.entries(cli.flags).filter(([, value]) => value !== undefined));
 
 	// Merge: local config → explicit CLI flags → defaults
-	const flags = {
+	const mergedFlags = {
 		cleanup: true,
 		tests: true,
 		publish: true,
@@ -144,6 +146,9 @@ async function getOptions() {
 		...explicitCliFlags,
 	};
 
+	const {preview, ...flags} = mergedFlags;
+	flags.dryRun ??= preview;
+
 	// Workaround for unintended auto-casing behavior from `meow`.
 	if ('2Fa' in flags) {
 		flags['2fa'] = flags['2Fa'];
@@ -223,7 +228,7 @@ try {
 	console.log(); // Prints a newline for readability
 	const newPackage = await np(options.version.toString(), options, {package_, projectDirectory, rootDirectory});
 
-	if (options.preview || options.releaseDraftOnly) {
+	if (options.dryRun || options.releaseDraftOnly) {
 		gracefulExit();
 	}
 

source/index.js

@@ -54,8 +54,12 @@ const exec = (command, arguments_, options) => {
 @param {import('./cli-implementation.js').Options} options
 @param {{package_: import('read-pkg').NormalizedPackageJson; projectDirectory?: string; rootDirectory: string}} context
 */
-const np = async (input = 'patch', {packageManager, ...options}, {package_, projectDirectory, rootDirectory}) => {
+const np = async (input = 'patch', {packageManager, ...rawOptions}, {package_, projectDirectory, rootDirectory}) => {
 	projectDirectory ??= rootDirectory;
+
+	const {preview, ...options} = rawOptions;
+	options.dryRun ??= preview;
+
 	// TODO: Remove sometime far in the future
 	if (options.skipCleanup) {
 		options.cleanup = false;
@@ -103,7 +107,7 @@ const np = async (input = 'patch', {packageManager, ...options}, {package_, proj
 	});
 
 	asyncExitHook(async () => {
-		if (options.preview || publishStatus === 'SUCCESS') {
+		if (options.dryRun || publishStatus === 'SUCCESS') {
 			return;
 		}
 
@@ -152,8 +156,8 @@ const np = async (input = 'patch', {packageManager, ...options}, {package_, proj
 			title: 'Cleanup',
 			enabled: () => runCleanup && !lockfile,
 			skip() {
-				if (options.preview) {
-					return '[Preview] Command not executed: delete node_modules.';
+				if (options.dryRun) {
+					return '[Dry run] Command not executed: delete node_modules.';
 				}
 			},
 			task: () => deleteAsync(path.join(projectDirectory, 'node_modules')),
@@ -162,8 +166,8 @@ const np = async (input = 'patch', {packageManager, ...options}, {package_, proj
 			title: `Installing dependencies using ${packageManager.id}`,
 			enabled: () => runInstall,
 			skip() {
-				if (options.preview) {
-					return `[Preview] Command not executed: ${printCommand(getInstallCommand())}.`;
+				if (options.dryRun) {
+					return `[Dry run] Command not executed: ${printCommand(getInstallCommand())}.`;
 				}
 			},
 			task: () => new Listr([
@@ -183,23 +187,23 @@ const np = async (input = 'patch', {packageManager, ...options}, {package_, proj
 			title: 'Running tests',
 			enabled: () => runTests,
 			skip() {
-				if (options.preview) {
-					return `[Preview] Command not executed: ${packageManager.cli} run ${testScript}.`;
+				if (options.dryRun) {
+					return `[Dry run] Command not executed: ${packageManager.cli} run ${testScript}.`;
 				}
 			},
 			task: () => exec(packageManager.cli, ['run', testScript], {...ciEnvOptions, cwd: projectDirectory}),
 		},
 		{
 			title: 'Bumping version',
 			skip() {
-				if (options.preview) {
+				if (options.dryRun) {
 					const [cli, arguments_] = packageManager.versionCommand(input);
 
 					if (options.message) {
 						arguments_.push('--message', options.message.replaceAll('%s', input));
 					}
 
-					return `[Preview] Command not executed: ${printCommand([cli, arguments_])}`;
+					return `[Dry run] Command not executed: ${printCommand([cli, arguments_])}`;
 				}
 			},
 			task() {
@@ -218,9 +222,9 @@ const np = async (input = 'patch', {packageManager, ...options}, {package_, proj
 				{
 					title: 'Publishing package',
 					skip() {
-						if (options.preview) {
+						if (options.dryRun) {
 							const command = getPublishCommand(options);
-							return `[Preview] Command not executed: ${printCommand(command)}.`;
+							return `[Dry run] Command not executed: ${printCommand(command)}.`;
 						}
 					},
 					/** @type {(context, task) => Listr.ListrTaskResult<any>} */
@@ -252,9 +256,9 @@ const np = async (input = 'patch', {packageManager, ...options}, {package_, proj
 					? [{
 						title: 'Enabling two-factor authentication',
 						async skip() {
-							if (options.preview) {
+							if (options.dryRun) {
 								const arguments_ = await getEnable2faArguments(package_.name, options);
-								return `[Preview] Command not executed: npm ${arguments_.join(' ')}.`;
+								return `[Dry run] Command not executed: npm ${arguments_.join(' ')}.`;
 							}
 						},
 						task: (context, task) => enable2fa(task, package_.name, {otp: context.otp}),
@@ -269,9 +273,9 @@ const np = async (input = 'patch', {packageManager, ...options}, {package_, proj
 					return 'Upstream branch not found; not pushing.';
 				}
 
-				if (options.preview) {
+				if (options.dryRun) {
 					const remote = options.remote ? `${options.remote} ` : '';
-					return `[Preview] Command not executed: git push ${remote}--follow-tags.`;
+					return `[Dry run] Command not executed: git push ${remote}--follow-tags.`;
 				}
 
 				if (publishStatus === 'FAILED' && options.runPublish) {
@@ -287,8 +291,8 @@ const np = async (input = 'patch', {packageManager, ...options}, {package_, proj
 				title: 'Creating release draft on GitHub',
 				enabled: () => isOnGitHub === true,
 				skip() {
-					if (options.preview) {
-						return '[Preview] GitHub Releases draft will not be opened in preview mode.';
+					if (options.dryRun) {
+						return '[Dry run] GitHub Releases draft will not be opened in dry-run mode.';
 					}
 				},
 				task: () => releaseTaskHelper(options, package_, packageManager),
@@ -297,7 +301,7 @@ const np = async (input = 'patch', {packageManager, ...options}, {package_, proj
 	], {
 		showSubtasks: false,
 		renderer: options.renderer ?? 'default',
-		clearOutput: !options.preview && !options.releaseDraftOnly,
+		clearOutput: !options.dryRun && !options.releaseDraftOnly,
 	});
 
 	if (!options.runPublish) {

test/cli.js

@@ -1,5 +1,6 @@
 import path from 'node:path';
 import test from 'ava';
+import {execa} from 'execa';
 import {npPackage, npRootDirectory as rootDirectory} from '../source/util.js';
 import {cliPasses} from './_helpers/verify-cli.js';
 
@@ -22,7 +23,7 @@ test('flags: --help', cliPasses, cli, '--help', [
 	'--no-tests             Skips tests',
 	'--yolo                 Skips cleanup and testing',
 	'--no-publish           Skips publishing',
-	'--preview              Show tasks without actually executing them',
+	'--dry-run              Show tasks without actually executing them',
 	'--tag                  Publish under a given dist-tag',
 	'--contents             Subdirectory to publish',
 	'--no-release-draft     Skips opening a GitHub release draft',
@@ -45,3 +46,26 @@ test('flags: --help', cliPasses, cli, '--help', [
 ]);
 
 test('flags: --version', cliPasses, cli, '--version', [npPackage.version]);
+
+test('flags: --dry-run is shown in help', async t => {
+	const {stdout} = await execa(cli, ['--help']);
+
+	t.true(stdout.includes('--dry-run              Show tasks without actually executing them'));
+});
+
+test('flags: unknown flags fail', async t => {
+	const {exitCode, stderr} = await execa(cli, ['--wat'], {reject: false});
+
+	t.is(exitCode, 2);
+	t.true(stderr.includes('Unknown flag'));
+	t.true(stderr.includes('--wat'));
+});
+
+test('flags: --preview remains an alias for --dry-run', async t => {
+	const {exitCode, stderr} = await execa(cli, ['--preview', '--wat'], {reject: false});
+
+	t.is(exitCode, 2);
+	t.true(stderr.includes('Unknown flag'));
+	t.true(stderr.includes('--wat'));
+	t.false(stderr.includes('--preview'));
+});

test/index.js

@@ -299,7 +299,7 @@ test('install uses projectDirectory from context as cwd', async t => {
 		tests: false,
 		publish: false,
 		runPublish: false,
-		preview: false,
+		dryRun: false,
 	}, {package_: npPackageResult.package_, projectDirectory, rootDirectory: contentsDirectory});
 
 	t.deepEqual(execaStub.firstCall.args, ['npm', ['install', '--no-package-lock', '--no-production', '--engine-strict'], {cwd: projectDirectory}]);
@@ -332,7 +332,7 @@ test('cleanup uses projectDirectory from context', async t => {
 		tests: false,
 		publish: false,
 		runPublish: false,
-		preview: false,
+		dryRun: false,
 	}, {package_: npPackageResult.package_, projectDirectory, rootDirectory: contentsDirectory});
 
 	t.true(deleteAsyncStub.calledOnceWithExactly(path.join(projectDirectory, 'node_modules')));
@@ -361,7 +361,7 @@ test('tests use projectDirectory from context as cwd', async t => {
 		cleanup: false,
 		publish: false,
 		runPublish: false,
-		preview: false,
+		dryRun: false,
 	}, {package_: npPackageResult.package_, projectDirectory, rootDirectory: contentsDirectory});
 
 	t.deepEqual(execaStub.secondCall.args, ['npm', ['run', 'test'], {env: {CI: 'true'}, cwd: projectDirectory}]);
@@ -393,7 +393,7 @@ test('no-cleanup still uses lockfile-aware install command', async t => {
 		tests: false,
 		publish: false,
 		runPublish: false,
-		preview: false,
+		dryRun: false,
 	}, npPackageResult);
 
 	t.deepEqual(execaStub.firstCall.args, ['npm', ['ci', '--engine-strict'], {cwd: npPackageResult.rootDirectory}]);
@@ -427,7 +427,7 @@ test('contents mode looks up lockfile in projectDirectory and installs there', a
 		tests: false,
 		publish: false,
 		runPublish: false,
-		preview: false,
+		dryRun: false,
 	}, {package_: npPackageResult.package_, projectDirectory, rootDirectory});
 
 	t.true(findLockfileStub.calledOnceWithExactly(projectDirectory, packageManager));
@@ -474,7 +474,7 @@ test('contents mode keeps cleanup, install, and tests in projectDirectory while
 	t.is(publishCwd, rootDirectory);
 });
 
-test('preview with no-cleanup does not execute install command', async t => {
+test('dryRun with no-cleanup does not execute install command', async t => {
 	const execaStub = sinon.stub().returns(fakeExecaReturn());
 	const verifyWorkingTreeIsCleanStub = sinon.stub();
 
@@ -501,14 +501,46 @@ test('preview with no-cleanup does not execute install command', async t => {
 		tests: false,
 		publish: false,
 		runPublish: false,
-		preview: true,
+		dryRun: true,
 	}, npPackageResult);
 
 	t.true(execaStub.notCalled);
 	t.true(verifyWorkingTreeIsCleanStub.notCalled);
 });
 
-test('preview without lockfile does not clean up or run tests', async t => {
+test('dryRun without lockfile does not clean up or run tests', async t => {
+	const deleteAsyncStub = sinon.stub();
+	const execaStub = sinon.stub().returns(fakeExecaReturn());
+
+	/** @type {typeof np} */
+	const npMock = await esmock('../source/index.js', {
+		del: {deleteAsync: deleteAsyncStub},
+		execa: {execa: execaStub},
+		'../source/prerequisite-tasks.js': sinon.stub(),
+		'../source/git-tasks.js': sinon.stub(),
+		'../source/git-util.js': {
+			hasUpstream: sinon.stub().returns(true),
+			pushGraceful: sinon.stub(),
+			verifyWorkingTreeIsClean: sinon.stub(),
+		},
+		'../source/package-manager/index.js': {
+			...await import('../source/package-manager/index.js'),
+			findLockfile: sinon.stub().returns(undefined),
+		},
+	});
+
+	await npMock('1.0.0', {
+		...defaultOptions,
+		dryRun: true,
+		publish: false,
+		runPublish: false,
+	}, npPackageResult);
+
+	t.true(deleteAsyncStub.notCalled);
+	t.true(execaStub.notCalled);
+});
+
+test('preview option remains a supported alias for dryRun', async t => {
 	const deleteAsyncStub = sinon.stub();
 	const execaStub = sinon.stub().returns(fakeExecaReturn());