@wpelevator/wp-release 0.12.0 → 0.14.0

package/dist/cli.js

@@ -43,6 +43,7 @@ const globalArgs = {
     json: { type: 'boolean' },
     'github-output': { type: 'boolean' },
     config: { type: 'string' },
+    'tag-format': { type: 'string' },
 };
 const globalOptions = `Global options:
   -h, --help               Show help for the command
@@ -55,7 +56,32 @@ const globalOptions = `Global options:
       --json               Print the result as JSON
       --github-output      Set the result as JSON to the "result" output of
                            the GitHub Actions step
-      --config <path>      Path to a JavaScript release config file`;
+      --config <path>      Path to a JavaScript release config file
+      --tag-format <format>
+                           Tag format with {name}, {path} and {version} that
+                           replaces the tagFormat of the config, like
+                           {path}/{version}`;
+/**
+ * Get the config file and the tag format from the global options.
+ *
+ * @param  values Parsed CLI values.
+ * @return The --config and --tag-format values.
+ * @throws {ValidationError} For an empty --config or --tag-format.
+ */
+function getConfigArgs(values) {
+    const configFile = getString(values, 'config');
+    const tagFormat = getString(values, 'tag-format');
+    if ('' === configFile?.trim()) {
+        throw new ValidationError('--config <path> must not be empty.');
+    }
+    if ('' === tagFormat?.trim()) {
+        throw new ValidationError('--tag-format <format> must not be empty.');
+    }
+    return {
+        ...(configFile ? { configFile } : {}),
+        ...(tagFormat ? { tagFormat } : {}),
+    };
+}
 /**
  * Get the top-level help text listing all commands.
  *
@@ -176,11 +202,11 @@ function getGitHubOutputFile(values) {
  *
  * @param command Command definition with options and run().
  * @param args    Arguments after the command name.
- * @param io      Output streams and working directory.
+ * @param io      Input and output streams and working directory.
  * @return Exit code.
  */
 async function runCommand(command, args, io) {
-    const { stdout, stderr, cwd } = io;
+    const { stdin, stdout, stderr, cwd } = io;
     let logger = new Logger({ writer: new TextWriter({ stdout, stderr }) });
     try {
         const { values, positionals } = parseArgs({
@@ -188,22 +214,28 @@ async function runCommand(command, args, io) {
             options: { ...globalArgs, ...command.options },
             allowPositionals: true,
         });
-        const configFile = getString(values, 'config');
-        if ('' === configFile?.trim()) {
-            throw new ValidationError('--config <path> must not be empty.');
-        }
+        const { configFile, tagFormat } = getConfigArgs(values);
         const githubOutputFile = getGitHubOutputFile(values);
         logger = new Logger({
             writer: createLogWriter(values, { stdout, stderr }),
             quiet: getBoolean(values, 'quiet') || getBoolean(values, 'json'),
             verbose: getBoolean(values, 'verbose'),
         });
+        // Prompts need a person at a terminal, and would corrupt JSON output.
+        const interactive = true === stdin.isTTY &&
+            true === stdout.isTTY &&
+            !getBoolean(values, 'json') &&
+            !githubOutputFile;
         const { exitCode, result } = await command.run({
             values,
             positionals,
             cwd,
             ...(configFile ? { configFile } : {}),
+            ...(tagFormat ? { tagFormat } : {}),
             logger,
+            ...(interactive
+                ? { terminal: { input: stdin, output: stdout } }
+                : {}),
         });
         if (getBoolean(values, 'json')) {
             stdout.write(JSON.stringify(result, null, '\t') + '\n');
@@ -243,27 +275,27 @@ export async function execute(name, args, context) {
         options: { ...globalArgs, ...command.options },
         allowPositionals: true,
     });
-    const configFile = getString(values, 'config') ?? context.configFile;
-    if ('' === configFile?.trim()) {
-        throw new ValidationError('--config <path> must not be empty.');
-    }
+    const configArgs = getConfigArgs(values);
+    const configFile = configArgs.configFile ?? context.configFile;
+    const { tagFormat } = configArgs;
     // The command table is keyed by name, so the result matches CommandResults.
     return command.run({
         values,
         positionals,
         ...context,
         ...(configFile ? { configFile } : {}),
+        ...(tagFormat ? { tagFormat } : {}),
     });
 }
 /**
  * Run the CLI.
  *
  * @param args CLI arguments without the node and script paths.
- * @param io   Output streams and working directory.
+ * @param io   Input and output streams and working directory.
  * @return Exit code.
  */
 export async function run(args, io = {}) {
-    const { stdout = process.stdout, stderr = process.stderr, cwd = process.cwd(), } = io;
+    const { stdin = process.stdin, stdout = process.stdout, stderr = process.stderr, cwd = process.cwd(), } = io;
     const wantsHelp = args.includes('--help') || args.includes('-h');
     const command = findCommand(args);
     if (command && wantsHelp) {
@@ -271,7 +303,12 @@ export async function run(args, io = {}) {
         return EXIT_SUCCESS;
     }
     if (command) {
-        return runCommand(command, args.slice(1), { stdout, stderr, cwd });
+        return runCommand(command, args.slice(1), {
+            stdin,
+            stdout,
+            stderr,
+            cwd,
+        });
     }
     if (0 === args.length || wantsHelp || 'help' === args[0]) {
         stdout.write(getHelp() + '\n');

package/dist/commands/args.d.ts

@@ -1,5 +1,4 @@
 import type { ParseArgsOptionsConfig } from 'node:util';
-import type { FileRules } from '../file-selection.ts';
 import type { ParsedValues } from './command.ts';
 /**
  * Options shared by the commands that select files with .distignore and
@@ -40,26 +39,6 @@ export declare function checkDirectory(path: string): Promise<void>;
  * @return Whether the path is a directory.
  */
 export declare function isDirectory(path: string): Promise<boolean>;
-/**
- * Ignore a file that the command writes or reads, such as the checksums
- * manifest, when it's inside the selected directory.
- *
- * @param rules     Matcher from loadFileRules().
- * @param sourceDir Selected directory.
- * @param path      Absolute file path.
- * @return The same matcher.
- */
-export declare function ignoreOwnFile(rules: FileRules, sourceDir: string, path: string): FileRules;
-/**
- * Ignore the signature file that "wp-release sign" writes next to a file the
- * command writes, when it's inside the selected directory.
- *
- * @param rules     Matcher from loadFileRules().
- * @param sourceDir Selected directory.
- * @param path      Absolute path of the signed file.
- * @return The same matcher.
- */
-export declare function ignoreOwnSignature(rules: FileRules, sourceDir: string, path: string): FileRules;
 /**
  * Option for the source directory, which can also be the first positional
  * argument.

package/dist/commands/args.js

@@ -1,7 +1,6 @@
 import { stat } from 'node:fs/promises';
-import { isAbsolute, relative, resolve } from 'node:path';
+import { resolve } from 'node:path';
 import { ValidationError } from "../errors.js";
-import { SIGNATURE_EXTENSION } from "../signing.js";
 import { getBoolean, getString, getStrings } from "./command.js";
 /**
  * Options shared by the commands that select files with .distignore and
@@ -63,39 +62,6 @@ export async function isDirectory(path) {
     const stats = await stat(path).catch(() => null);
     return Boolean(stats?.isDirectory());
 }
-/**
- * Ignore a file that the command writes or reads, such as the checksums
- * manifest, when it's inside the selected directory.
- *
- * @param rules     Matcher from loadFileRules().
- * @param sourceDir Selected directory.
- * @param path      Absolute file path.
- * @return The same matcher.
- */
-export function ignoreOwnFile(rules, sourceDir, path) {
-    const relativePath = relative(sourceDir, path).split('\\').join('/');
-    const isInside = relativePath &&
-        '..' !== relativePath &&
-        !relativePath.startsWith('../') &&
-        !isAbsolute(relativePath);
-    if (isInside) {
-        // Escape the gitignore wildcards so that the pattern matches only this file.
-        rules.add(`/${relativePath.replace(/[\\*?[\]!#]/g, '\\$&')}`);
-    }
-    return rules;
-}
-/**
- * Ignore the signature file that "wp-release sign" writes next to a file the
- * command writes, when it's inside the selected directory.
- *
- * @param rules     Matcher from loadFileRules().
- * @param sourceDir Selected directory.
- * @param path      Absolute path of the signed file.
- * @return The same matcher.
- */
-export function ignoreOwnSignature(rules, sourceDir, path) {
-    return ignoreOwnFile(rules, sourceDir, path + SIGNATURE_EXTENSION);
-}
 /**
  * Option for the source directory, which can also be the first positional
  * argument.

package/dist/commands/changeset-add.d.ts

@@ -22,15 +22,18 @@ declare const _default: {
         readonly empty: {
             readonly type: "boolean";
         };
+        readonly since: {
+            readonly type: "string";
+        };
         readonly name: {
             readonly type: "string";
         };
     };
-    run({ values, cwd, configFile, logger }: import("./command.ts").CommandContext): Promise<{
+    run({ values, cwd, configFile, tagFormat, logger, terminal }: import("./command.ts").CommandContext): Promise<{
         exitCode: number;
         result: {
             file: string;
-            packages: import("../changesets.ts").ChangesetPackages;
+            packages: any;
         };
     }>;
 };

package/dist/commands/changeset-add.js

@@ -1,34 +1,134 @@
-import { addChangeset } from "../changeset-release.js";
+import { resolvePackageNames } from "../changeset-packages.js";
+import { ChangesetPrompt } from "../changeset-prompt.js";
+import { ChangesetRelease } from "../changeset-release.js";
+import { ValidationError } from "../errors.js";
 import { parseChangesetAddArgs, changesetAddArgs } from "./changeset-args.js";
+/**
+ * Get the bumps of the changed packages that have no changeset yet.
+ *
+ * @param  release Changeset release of the repository.
+ * @param  input   Parsed options with the base ref.
+ * @param  bump    Bump of the changed packages.
+ * @return Bump of each changed package.
+ * @throws {ValidationError} If no changed package needs a changeset.
+ */
+async function getChangedPackageBumps(release, input, bump) {
+    const status = await release.getStatus({
+        ...(input.since ? { since: input.since } : {}),
+        uncommitted: true,
+    });
+    if (!status.missingChangesets.length) {
+        const since = status.since ? ` since ${status.since}` : '';
+        throw new ValidationError(`No package changed${since} without a changeset. Pass --package <name> to choose the packages.`);
+    }
+    return Object.fromEntries(status.missingChangesets.map((name) => [name, bump]));
+}
+/**
+ * Ask for the changeset, preselecting the changed packages without one.
+ *
+ * @param release  Changeset release of the repository.
+ * @param input    Parsed options with the base ref and release note.
+ * @param terminal Terminal to ask in.
+ * @return Package bumps and release note.
+ */
+async function askChangeset(release, input, terminal) {
+    const packages = await release.getPackages();
+    const status = await release.getStatus({
+        ...(input.since ? { since: input.since } : {}),
+        uncommitted: true,
+    });
+    const prompt = new ChangesetPrompt(terminal);
+    try {
+        return await prompt.ask({
+            packages,
+            changed: status.missingChangesets,
+            ...(status.since ? { since: status.since } : {}),
+            ...(input.summary ? { summary: input.summary } : {}),
+        });
+    }
+    finally {
+        prompt.close();
+    }
+}
+/**
+ * Get the package bumps and release note from the options, the changed
+ * packages or the prompts.
+ *
+ * @param  release  Changeset release of the repository.
+ * @param  input    Parsed options.
+ * @param  terminal Terminal to ask in, when the CLI runs in one.
+ * @return Package bumps, empty for no release, and release note.
+ * @throws {ValidationError} Without packages outside a terminal.
+ */
+async function getChangeset(release, input, terminal) {
+    const summary = input.summary ?? '';
+    let changeset;
+    if (input.empty) {
+        changeset = { packages: {}, summary };
+    }
+    else if (Object.keys(input.packages).length) {
+        changeset = { packages: input.packages, summary };
+    }
+    else if (input.bump) {
+        changeset = {
+            packages: await getChangedPackageBumps(release, input, input.bump),
+            summary,
+        };
+    }
+    else if (terminal) {
+        changeset = await askChangeset(release, input, terminal);
+    }
+    else {
+        throw new ValidationError('Pass matching repeated --package <name> and --bump <patch|minor|major> options, a single --bump for the changed packages, or --empty.');
+    }
+    return changeset;
+}
 export default {
     name: 'changeset-add',
-    usage: 'changeset-add (--empty | --package <name> --bump <bump> ...) [options]',
+    usage: 'changeset-add [--empty | --package <name> --bump <bump> ... | --bump <bump>] [options]',
     summary: 'Add a package release note for the next release PR.',
     help: `Options:
-  --package <name>       Package identifier (repeatable)
+  --package <name>       Package identifier, or its path under the configured
+                         root (repeatable)
   --bump <bump>          patch, minor or major (repeatable, in package order)
   --summary <text>       Customer-facing release note
   --empty                Record that this change does not need a release
+  --since <ref>          Compare changed files with this git ref (default:
+                         <remote>/<baseBranch>)
   --name <name>          Changeset filename (default: random identifier)
 
 Use --package and --bump pairs for package releases, or --empty for changes
-that should pass the status check without producing a release.`,
+that should pass the status check without producing a release. A single
+--bump without --package releases the packages that changed since the base
+ref, including uncommitted files, and have no changeset yet. Without
+--package and --bump in a terminal, the command asks for the packages, with
+the changed ones preselected, their bumps and the release note.`,
     options: changesetAddArgs,
-    async run({ values, cwd, configFile, logger }) {
+    async run({ values, cwd, configFile, tagFormat, logger, terminal }) {
         const input = parseChangesetAddArgs(values);
-        const file = await addChangeset({
+        const release = new ChangesetRelease({
             cwd,
             ...(configFile ? { configFile } : {}),
-            packages: input.packages,
-            summary: input.summary,
+            ...(tagFormat ? { tagFormat } : {}),
+        });
+        const changeset = await getChangeset(release, input, terminal);
+        // Adding resolves the package paths and rejects a package passed twice.
+        const file = await release.add({
+            packages: changeset.packages,
+            summary: changeset.summary,
             ...(input.name ? { name: input.name } : {}),
         });
+        const names = resolvePackageNames(await release.getPackages(), Object.keys(changeset.packages));
+        const packages = Object.fromEntries(Object.values(changeset.packages).map((bump, index) => [
+            names[index],
+            bump,
+        ]));
         logger.info(`Created ${file}.`);
         return {
             exitCode: 0,
             result: {
                 file,
-                packages: input.packages,
+                packages,
             },
         };
     },

package/dist/commands/changeset-args.d.ts

@@ -1,10 +1,14 @@
-import type { ChangesetPackages } from '../changesets.ts';
+import type { ChangesetBump, ChangesetPackages } from '../changesets.ts';
 import type { ParsedValues } from './command.ts';
 /** Parsed input for `changeset-add`. */
 export interface ChangesetAddArgs {
+    /** Bump of each package passed with --package, by identifier or path. */
     packages: ChangesetPackages;
-    summary: string;
+    /** Bump for the changed packages without a changeset, passed without --package. */
+    bump?: ChangesetBump;
+    summary?: string;
     empty: boolean;
+    since?: string;
     name?: string;
 }
 /** Parse-args options for `changeset-add`. */
@@ -23,16 +27,21 @@ export declare const changesetAddArgs: {
     readonly empty: {
         readonly type: "boolean";
     };
+    readonly since: {
+        readonly type: "string";
+    };
     readonly name: {
         readonly type: "string";
     };
 };
 /**
- * Parse and validate the `changeset-add` options.
+ * Parse and validate the `changeset-add` options. Without --package, a
+ * single --bump applies to the changed packages without a changeset, and
+ * without --bump either the command asks for the changeset in a terminal.
  *
  * @param  values Parsed CLI options.
  * @return Normalized changeset input.
- * @throws {ValidationError} If required options are missing or conflicting.
+ * @throws {ValidationError} If options are conflicting or incomplete.
  */
 export declare function parseChangesetAddArgs(values: ParsedValues): ChangesetAddArgs;
 /** Parse-args options for `changeset-status`. */
@@ -68,6 +77,12 @@ export declare const changesetVersionArgs: {
     readonly 'no-dependents': {
         readonly type: "boolean";
     };
+    readonly prerelease: {
+        readonly type: "string";
+    };
+    readonly snapshot: {
+        readonly type: "string";
+    };
 };
 /** Parsed input for `changeset-version`. */
 export interface ChangesetVersionArgs {
@@ -76,6 +91,10 @@ export interface ChangesetVersionArgs {
     packages?: string[];
     /** Whether the selected sources release their configured dependents; defaults to true. */
     dependents: boolean;
+    /** Pre-release identifier with an optional number, like rc or rc.1. */
+    prerelease?: string;
+    /** Snapshot identifier, like pr-251. */
+    snapshot?: string;
 }
 /**
  * Validate and normalize a release date option.
@@ -90,7 +109,7 @@ export declare function parseChangesetDate(value: string | undefined): string |
  *
  * @param  values Parsed CLI options.
  * @return Normalized versioning input.
- * @throws {ValidationError} If --date is invalid.
+ * @throws {ValidationError} If --date is invalid, or an option is empty or conflicting.
  */
 export declare function parseChangesetVersionArgs(values: ParsedValues): ChangesetVersionArgs;
 /** Parse-args options for `changeset-tag`. */

package/dist/commands/changeset-args.js

@@ -7,48 +7,76 @@ export const changesetAddArgs = {
     bump: { type: 'string', multiple: true },
     summary: { type: 'string' },
     empty: { type: 'boolean' },
+    since: { type: 'string' },
     name: { type: 'string' },
 };
 /**
- * Parse and validate the `changeset-add` options.
+ * Check that a bump is patch, minor or major.
+ *
+ * @param  bump        Bump option value.
+ * @param  packageName Package of the bump, for the error.
+ * @return The bump.
+ * @throws {ValidationError} For another value.
+ */
+function parseBump(bump, packageName) {
+    if (!CHANGESET_BUMPS.includes(bump)) {
+        const target = packageName ? ` for package "${packageName}"` : '';
+        throw new ValidationError(`Invalid bump "${bump}"${target}; expected patch, minor or major.`);
+    }
+    return bump;
+}
+/**
+ * Parse and validate the `changeset-add` options. Without --package, a
+ * single --bump applies to the changed packages without a changeset, and
+ * without --bump either the command asks for the changeset in a terminal.
  *
  * @param  values Parsed CLI options.
  * @return Normalized changeset input.
- * @throws {ValidationError} If required options are missing or conflicting.
+ * @throws {ValidationError} If options are conflicting or incomplete.
  */
 export function parseChangesetAddArgs(values) {
     const names = getStrings(values, 'package');
     const bumps = getStrings(values, 'bump');
     const summary = getString(values, 'summary')?.trim();
     const empty = getBoolean(values, 'empty');
+    const since = getString(values, 'since');
     const name = getString(values, 'name');
-    if (empty && (names.length || bumps.length || summary)) {
-        throw new ValidationError('--empty cannot be combined with --package, --bump or --summary.');
+    if (empty && (names.length || bumps.length || summary || since)) {
+        throw new ValidationError('--empty cannot be combined with --package, --bump, --summary or --since.');
     }
-    if (!empty && (!names.length || names.length !== bumps.length)) {
+    if (names.length && names.length !== bumps.length) {
         throw new ValidationError('Pass matching repeated --package <name> and --bump <patch|minor|major> options, or use --empty.');
     }
-    if (!empty && !summary) {
-        throw new ValidationError('--summary <text> is required unless --empty is set.');
+    if (!names.length && bumps.length > 1) {
+        throw new ValidationError('Pass a single --bump without --package to release the changed packages, or pair each --bump with a --package.');
+    }
+    if (names.length && undefined !== since) {
+        throw new ValidationError('--since selects the changed packages, so it cannot be combined with --package.');
+    }
+    if ('' === since?.trim()) {
+        throw new ValidationError('--since <ref> must not be empty.');
+    }
+    if (bumps.length && !summary) {
+        throw new ValidationError('--summary <text> is required with --bump.');
     }
     if (name && !/^[a-zA-Z0-9][a-zA-Z0-9._-]*$/.test(name)) {
         throw new ValidationError('--name must contain only letters, numbers, dots, underscores or hyphens.');
     }
     const packages = {};
     names.forEach((packageName, index) => {
-        const bump = bumps[index];
         if (Object.hasOwn(packages, packageName)) {
             throw new ValidationError(`Package "${packageName}" was passed more than once.`);
         }
-        if (!CHANGESET_BUMPS.includes(bump)) {
-            throw new ValidationError(`Invalid bump "${bump}" for package "${packageName}"; expected patch, minor or major.`);
-        }
-        packages[packageName] = bump;
+        packages[packageName] = parseBump(bumps[index] ?? '', packageName);
     });
     return {
         packages,
-        summary: summary ?? '',
         empty,
+        ...(!names.length && bumps.length
+            ? { bump: parseBump(bumps[0] ?? '') }
+            : {}),
+        ...(summary ? { summary } : {}),
+        ...(since ? { since } : {}),
         ...(name ? { name } : {}),
     };
 }
@@ -76,6 +104,8 @@ export const changesetVersionArgs = {
     date: { type: 'string' },
     package: { type: 'string', multiple: true },
     'no-dependents': { type: 'boolean' },
+    prerelease: { type: 'string' },
+    snapshot: { type: 'string' },
 };
 /**
  * Validate and normalize a release date option.
@@ -102,19 +132,32 @@ export function parseChangesetDate(value) {
  *
  * @param  values Parsed CLI options.
  * @return Normalized versioning input.
- * @throws {ValidationError} If --date is invalid.
+ * @throws {ValidationError} If --date is invalid, or an option is empty or conflicting.
  */
 export function parseChangesetVersionArgs(values) {
     const date = parseChangesetDate(getString(values, 'date'));
     const packages = getStrings(values, 'package');
+    const prerelease = getString(values, 'prerelease')?.trim();
     if (packages.some((name) => !name.trim())) {
         throw new ValidationError('--package <name> must not be empty.');
     }
+    const snapshot = getString(values, 'snapshot')?.trim();
+    if ('' === prerelease) {
+        throw new ValidationError('--prerelease <id> must not be empty.');
+    }
+    if ('' === snapshot) {
+        throw new ValidationError('--snapshot <id> must not be empty.');
+    }
+    if (prerelease && snapshot) {
+        throw new ValidationError('--prerelease cannot be combined with --snapshot.');
+    }
     return {
         dryRun: getBoolean(values, 'dry-run'),
         dependents: !getBoolean(values, 'no-dependents'),
         ...(date ? { date } : {}),
         ...(packages.length ? { packages } : {}),
+        ...(prerelease ? { prerelease } : {}),
+        ...(snapshot ? { snapshot } : {}),
     };
 }
 /** Parse-args options for `changeset-tag`. */

package/dist/commands/changeset-status.d.ts

@@ -1,4 +1,5 @@
 export interface ChangesetStatusResult {
+    since?: string;
     changesets: Array<{
         fileName: string;
         packages: Record<string, string>;
@@ -25,7 +26,7 @@ declare const _default: {
             readonly type: "string";
         };
     };
-    run({ values, cwd, configFile, logger }: import("./command.ts").CommandContext): Promise<{
+    run({ values, cwd, configFile, tagFormat, logger }: import("./command.ts").CommandContext): Promise<{
         exitCode: number;
         result: {
             releases: {
@@ -34,6 +35,7 @@ declare const _default: {
                 currentVersion: string;
                 nextVersion: string;
             }[];
+            since?: string;
             changesets: import("../changesets.ts").Changeset[];
             changedPackages: string[];
             changedPackageFiles: Record<string, string[]>;

package/dist/commands/changeset-status.js

@@ -10,11 +10,12 @@ export default {
 Exit status is 2 when a changed package has no changeset added since the comparison base.
 An empty changeset added since the comparison base counts as an explicit no-release decision.`,
     options: changesetStatusArgs,
-    async run({ values, cwd, configFile, logger }) {
+    async run({ values, cwd, configFile, tagFormat, logger }) {
         const { since } = parseChangesetStatusArgs(values);
         const result = await getChangesetStatus({
             cwd,
             ...(configFile ? { configFile } : {}),
+            ...(tagFormat ? { tagFormat } : {}),
             ...(since ? { since } : {}),
         });
         logger.summary(() => {

package/dist/commands/changeset-tag.d.ts

@@ -24,7 +24,7 @@ declare const _default: {
             readonly type: "string";
         };
     };
-    run({ values, cwd, configFile, logger }: import("./command.ts").CommandContext): Promise<{
+    run({ values, cwd, configFile, tagFormat, logger }: import("./command.ts").CommandContext): Promise<{
         exitCode: number;
         result: import("../changeset-release.ts").ChangesetTagResult;
     }>;

package/dist/commands/changeset-tag.js

@@ -10,10 +10,12 @@ export default {
                          creating them
   --untagged             List only releases without a tag, without creating tags
   --since <ref>          Tag packages changed since this git ref
-  --package <name>       Tag only this package (repeatable)
+  --package <name>       Tag only this package, by identifier or path under
+                         the configured root (repeatable)
   --version <version>    Fail unless the single --package is at this version;
                          the version to tag for packages versioned by git tags
-  --push                 Push newly created tags to origin, one at a time
+  --push                 Push newly created tags to the configured remote
+                         (default: origin), one at a time
 
 Tags are created only when absent, so rerunning after a partial failure is
 safe. Before a tag is created, every configured version target must match the
@@ -22,11 +24,12 @@ and pre-release flag of its release, for a workflow step that creates the
 GitHub Release. --untagged lists only the releases that still need a tag, for
 example to release each of them with a separate workflow.`,
     options: changesetTagArgs,
-    async run({ values, cwd, configFile, logger }) {
+    async run({ values, cwd, configFile, tagFormat, logger }) {
         const args = parseChangesetTagArgs(values);
         const result = await tagChangesets({
             cwd,
             ...(configFile ? { configFile } : {}),
+            ...(tagFormat ? { tagFormat } : {}),
             ...args,
         });
         result.tags.forEach((item) => {