keepchanges 1.0.0-beta.3 → 1.0.1

package/README.md

@@ -49,9 +49,9 @@ npx keepchanges <version> [options]
 
 | Argument or option | Default | Description |
 | --- | --- | --- |
-| `<version>` | Required | Version to generate. Accepts `1.1.0` or `v1.1.0`; headings and tags use `v1.1.0`. A version containing `-`, such as `1.1.0-beta.1`, is treated as a prerelease. |
-| `--from <ref>` | Latest tag | Overrides the starting Git ref used to read commits. |
-| `--to <ref>` | `HEAD` | Sets the ending Git ref. It cannot be combined with `--release`, and must resolve to the current `HEAD` when used with `--commit`. |
+| `<version>` | Required | Version to generate. Accepts `1.1.0` or `v1.1.0`. A version containing `-`, such as `1.1.0-beta.1`, is treated as a prerelease. |
+| `--from <ref>` | Latest matching tag | Overrides the starting Git ref used to read commits. A version such as `1.0.0` uses the configured tag prefix. |
+| `--to <ref>` | `HEAD` | Sets the ending Git ref. A version such as `1.1.0` uses the configured tag prefix. It cannot be combined with `--release`, and must resolve to the current `HEAD` when used with `--commit`. |
 | `--repository <source>` | Auto-detected | Sets a GitHub `owner/repo` slug or a complete GitHub/Gitea URL. It takes precedence over `package.json` and `origin`. |
 | `--output <path>` | `CHANGELOG.md` | Sets the changelog file path. Relative paths are resolved from the current working directory. |
 | `--dry` | `false` | Prints the current release preview without writing files or performing commit, tag, push, or release API mutations. |
@@ -59,6 +59,8 @@ npx keepchanges <version> [options]
 | `--release` | `false` | Runs the complete release flow: writes files, creates or reuses a release commit, creates an annotated tag, pushes `HEAD` and the tag, then creates or updates the repository Release. This implies `--commit`. |
 | `--author <author>` | Release bot | Sets the generated release commit author in `"Name <email>"` format; requires `--commit` or `--release`. |
 | `-t, --token <token>` | Environment | Resolves authors and publishes Releases. GitHub precedence is `--token`, `GITHUB_TOKEN`, then `GH_TOKEN`; Gitea uses `GITEA_TOKEN`. |
+| `--tag-prefix <prefix>` | `v` | Sets the prefix used to find and create version tags, such as `package@`. |
+| `--no-tag-prefix` | `false` | Finds and creates version tags without a prefix. |
 | `--name <name>` | Version tag | Sets the remote Release name; only valid with `--release`. |
 | `-d, --draft` | `false` | Creates a draft Release; only valid with `--release`. |
 | `--prerelease` | Inferred | Explicitly marks a prerelease. By default it is inferred from `-` in the version; only valid with `--release`. |
@@ -99,6 +101,18 @@ Create a GitHub Release:
 GITHUB_TOKEN=github_pat_xxx npx keepchanges 1.1.0 --release
 ```
 
+Use version tags without a prefix:
+
+```bash
+npx keepchanges 1.1.0 --no-tag-prefix
+```
+
+Use a package-specific tag prefix:
+
+```bash
+npx keepchanges 1.1.0 --tag-prefix 'package@'
+```
+
 Preview a Release without writing, committing, tagging, pushing, or calling the
 release API:
 
@@ -127,6 +141,12 @@ and the release ends with a version comparison link. GitHub and Gitea both
 support author resolution and Release publishing. Gitea uses `GITEA_TOKEN` to
 resolve primary commit authors and publish Releases.
 
+Version tags use the `v` prefix by default. The configured prefix applies to
+new tags, existing-tag lookup, version-shaped `--from` and `--to` values,
+comparison links, and repository Release names. Branch names, commit hashes,
+`HEAD`, and other non-version refs are used unchanged. Tag lookup only considers
+the configured prefix, so independent tag sequences do not affect each other.
+
 Entries use Git author names by default and include `Co-Authored-By`
 participants. Bot accounts are omitted. With the corresponding provider token,
 the CLI attempts to resolve email addresses to usernames.

package/README.zh-CN.md

@@ -48,9 +48,9 @@ npx keepchanges <version> [options]
 
 | 参数 | 默认值 | 说明 |
 | --- | --- | --- |
-| `<version>` | 必填 | 要生成的版本号。可以传入 `1.1.0` 或 `v1.1.0`；生成的标题和 tag 统一使用 `v1.1.0`。包含 `-` 的版本会作为预发布版本，例如 `1.1.0-beta.1`。 |
-| `--from <ref>` | 最近的 tag | 指定读取 commit 的起始 Git ref，并覆盖自动选择结果。 |
-| `--to <ref>` | `HEAD` | 指定读取 commit 的结束 Git ref。不能与 `--release` 一起使用；与 `--commit` 一起使用时必须指向当前 `HEAD`。 |
+| `<version>` | 必填 | 要生成的版本号。可以传入 `1.1.0` 或 `v1.1.0`。包含 `-` 的版本会作为预发布版本，例如 `1.1.0-beta.1`。 |
+| `--from <ref>` | 匹配前缀的最近 tag | 指定读取 commit 的起始 Git ref，并覆盖自动选择结果。`1.0.0` 这类版本会自动应用配置的 tag 前缀。 |
+| `--to <ref>` | `HEAD` | 指定读取 commit 的结束 Git ref。`1.1.0` 这类版本会自动应用配置的 tag 前缀。不能与 `--release` 一起使用；与 `--commit` 一起使用时必须指向当前 `HEAD`。 |
 | `--repository <source>` | 自动检测 | 指定 `owner/repo` 格式的 GitHub 仓库或 GitHub/Gitea 完整 URL。优先级高于 `package.json` 和 `origin`。 |
 | `--output <path>` | `CHANGELOG.md` | 指定 changelog 文件路径。相对路径以当前工作目录为基准。 |
 | `--dry` | `false` | 输出当前版本预览，不写入文件，也不执行 commit、tag、push 或发布 API。 |
@@ -58,6 +58,8 @@ npx keepchanges <version> [options]
 | `--release` | `false` | 执行完整发布流程：写入文件、创建或复用 release commit、创建 annotated tag、推送 `HEAD` 和 tag，然后创建或更新仓库 Release。该参数隐含 `--commit`。 |
 | `--author <author>` | release bot | 设置自动创建的 release commit 作者，格式必须为 `"Name <email>"`；需要与 `--commit` 或 `--release` 一起使用。 |
 | `-t, --token <token>` | 环境变量 | 仓库访问令牌，用于解析作者及发布 Release。GitHub 优先级为 `--token`、`GITHUB_TOKEN`、`GH_TOKEN`；Gitea 使用 `GITEA_TOKEN`。 |
+| `--tag-prefix <prefix>` | `v` | 设置查找和创建版本 tag 时使用的前缀，例如 `package@`。 |
+| `--no-tag-prefix` | `false` | 查找和创建不带前缀的版本 tag。 |
 | `--name <name>` | 版本 tag | 设置远程 Release 名称；仅适用于 `--release`。 |
 | `-d, --draft` | `false` | 创建 draft Release；仅适用于 `--release`。 |
 | `--prerelease` | 根据版本推断 | 显式标记为 prerelease；默认根据版本是否包含 `-` 推断，仅适用于 `--release`。 |
@@ -98,6 +100,18 @@ npx keepchanges 1.1.0 --commit \
 GITHUB_TOKEN=github_pat_xxx npx keepchanges 1.1.0 --release
 ```
 
+使用无前缀版本 tag：
+
+```bash
+npx keepchanges 1.1.0 --no-tag-prefix
+```
+
+使用 package 专属 tag 前缀：
+
+```bash
+npx keepchanges 1.1.0 --tag-prefix 'package@'
+```
+
 预览 Release，不写文件、不提交、不创建 tag、不推送且不调用发布 API：
 
 ```bash
@@ -123,6 +137,11 @@ GitHub 地址会被自动识别。自托管 Gitea 需要在 `package.json` 中
 GitHub 和 Gitea 均支持作者解析和 Release 发布；Gitea 使用 `GITEA_TOKEN`
 解析 commit 主作者并发布 Release。
 
+版本 tag 默认使用 `v` 前缀。配置的前缀会统一应用于新 tag、已有 tag 查找、
+版本形式的 `--from` 和 `--to`、比较链接及仓库 Release 名称。分支名、commit
+hash、`HEAD` 等非版本 ref 保持不变。自动查找 tag 时只考虑配置的前缀，因此
+彼此独立的 tag 序列不会相互影响。
+
 默认使用 Git 提交中的作者名，并将 `Co-Authored-By` 参与者一起写入记录，bot
 账号会被忽略。提供对应平台的 token 后，会尝试将邮箱解析为用户名。
 

package/dist/cli.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { a as insertRelease, c as defaultConfig, i as hasRelease, n as parseCommits, o as readChangelog, r as generateChangelog, s as writeChangelog } from "./commit-FX77u6Sj.mjs";
+import { a as insertRelease, c as defaultConfig, i as hasRelease, n as parseCommits, o as readChangelog, r as generateChangelog, s as writeChangelog } from "./commit-DBopyhs1.mjs";
 import { readFile, writeFile } from "node:fs/promises";
 import { normalizeFull } from "verkit";
 import process from "node:process";
@@ -8,30 +8,47 @@ import { resolve } from "node:path";
 import ansis from "ansis";
 import { x } from "tinyexec";
 //#region package.json
-var version = "1.0.0-beta.3";
+var version = "1.0.1";
 //#endregion
 //#region src/git.ts
+function versionTagPattern(tagPrefix) {
+	return `${tagPrefix.replace(/[\\*?[\]]/g, "\\$&")}[0-9]*`;
+}
 async function git(cwd, ...args) {
 	const result = await x("git", args, { nodeOptions: { cwd } });
 	if (result.exitCode !== 0) throw new Error(result.stderr.trim() || `Git exited with status ${result.exitCode}`);
 	return result.stdout;
 }
-async function getLatestTag(cwd) {
-	return (await x("git", [
+async function getLatestTag(cwd, tagPrefix) {
+	const args = [
 		"describe",
 		"--tags",
 		"--abbrev=0"
-	], { nodeOptions: { cwd } })).stdout.trim();
+	];
+	if (tagPrefix !== void 0) args.push("--match", versionTagPattern(tagPrefix));
+	return (await x("git", args, { nodeOptions: { cwd } })).stdout.trim();
 }
 async function getTagCommit(cwd, tag) {
 	return git(cwd, "rev-list", "-n", "1", tag).then((output) => output.trim() || void 0).catch(() => void 0);
 }
-async function getPreviousTag(cwd, tag, releaseRef) {
-	if (!tag.includes("-")) {
-		const previousStable = (await git(cwd, "tag", "--merged", releaseRef, "--sort=-version:refname")).trim().split("\n").find((candidate) => candidate !== tag && /^v?\d+\.\d+\.\d+$/.test(candidate));
+async function resolveVersionRef(cwd, ref, tagPrefix) {
+	const version = normalizeFull(ref);
+	if (!version) return ref;
+	const candidates = [.../* @__PURE__ */ new Set([`${tagPrefix}${version}`, ref])];
+	for (const candidate of candidates) if (await getTagCommit(cwd, `refs/tags/${candidate}`)) return candidate;
+	return ref;
+}
+async function getPreviousTag(cwd, tag, releaseRef, tagPrefix) {
+	const releaseVersion = normalizeFull(tag.slice(tagPrefix.length));
+	if (releaseVersion && !releaseVersion.includes("-")) {
+		const previousStable = (await git(cwd, "tag", "--merged", releaseRef, "--sort=-version:refname")).trim().split("\n").find((candidate) => {
+			if (candidate === tag || !candidate.startsWith(tagPrefix)) return false;
+			const version = normalizeFull(candidate.slice(tagPrefix.length));
+			return Boolean(version && !version.includes("-"));
+		});
 		if (previousStable) return previousStable;
 	}
-	return git(cwd, "describe", "--tags", "--abbrev=0", `${releaseRef}^`).then((output) => output.trim()).catch(() => "");
+	return git(cwd, "describe", "--tags", "--abbrev=0", "--match", versionTagPattern(tagPrefix), `${releaseRef}^`).then((output) => output.trim()).catch(() => "");
 }
 async function getRemoteTagCommit(cwd, tag) {
 	const refs = (await git(cwd, "ls-remote", "--tags", "origin", `refs/tags/${tag}`, `refs/tags/${tag}^{}`)).trim().split("\n").filter(Boolean);
@@ -320,7 +337,7 @@ async function createChanges(options, environment) {
 	const env = environment.env ?? process.env;
 	const stdout = environment.stdout ?? ((value) => process.stdout.write(value));
 	const colors = environment.colors ?? ansis;
-	const tag = `v${options.version}`;
+	const tag = `${options.tagPrefix}${options.version}`;
 	const repository = await resolveRepository(environment.cwd, options.repository);
 	const token = repository?.provider.token(options.token, env);
 	validateReleaseSupport(options, repository);
@@ -336,10 +353,12 @@ async function createChanges(options, environment) {
 		taggedCommit = await getTagCommit(environment.cwd, tag);
 		releaseRef = tag;
 	}
-	const from = options.from ?? (taggedCommit ? await getPreviousTag(environment.cwd, tag, releaseRef) : await getLatestTag(environment.cwd));
+	const from = options.from ?? (taggedCommit ? await getPreviousTag(environment.cwd, tag, releaseRef, options.tagPrefix) : await getLatestTag(environment.cwd, options.tagPrefix));
 	const to = releaseRef || options.to;
-	const comparisonFrom = from || (repository ? await git(environment.cwd, "rev-list", "--max-parents=0", to).then((value) => value.trim()) : "");
-	const commits = parseCommits(await readGitCommits(environment.cwd, from, to));
+	const resolvedFrom = from ? await resolveVersionRef(environment.cwd, from, options.tagPrefix) : "";
+	const resolvedTo = await resolveVersionRef(environment.cwd, to, options.tagPrefix);
+	const comparisonFrom = resolvedFrom || (repository ? await git(environment.cwd, "rev-list", "--max-parents=0", resolvedTo).then((value) => value.trim()) : "");
+	const commits = parseCommits(await readGitCommits(environment.cwd, resolvedFrom, resolvedTo));
 	if (token && repository) await repository.provider.resolveAuthors?.(commits, repository, token, environment.fetch ?? globalThis.fetch);
 	const style = {
 		emoji: options.emoji,
@@ -350,7 +369,8 @@ async function createChanges(options, environment) {
 		version: options.version,
 		commits,
 		repository,
-		comparisonFrom
+		comparisonFrom,
+		comparisonTo: normalizeFull(options.to) ? resolvedTo : tag
 	}, style);
 	const repositoryRelease = {
 		tag,
@@ -360,7 +380,7 @@ async function createChanges(options, environment) {
 		draft: options.draft
 	};
 	const preview = {
-		from: from || comparisonFrom,
+		from: resolvedFrom || comparisonFrom,
 		tag,
 		commitCount: commits.length,
 		body
@@ -383,7 +403,7 @@ async function createChanges(options, environment) {
 	const releaseExists = hasRelease(currentChangelog, options.version);
 	await writeChangelog(outputPath, insertRelease(currentChangelog, release));
 	const versionPath = await updateVersion(environment.cwd, options.version);
-	if (options.commit || options.release) await commitReleaseFiles(options, environment.cwd, outputPath, versionPath, releaseExists);
+	if (options.commit || options.release) await commitReleaseFiles(options, environment.cwd, outputPath, versionPath, releaseExists, tag);
 	if (options.release) {
 		const gitIdentity = resolveGitIdentity(options.author);
 		await git(environment.cwd, ...gitIdentity, "tag", "-a", tag, "-m", tag);
@@ -396,12 +416,12 @@ function validateReleaseSupport(options, repository) {
 	if (!repository) throw new Error("A supported repository is required to release");
 	if (!repository.provider.publishRelease && !repository.provider.manualReleaseUrl) throw new Error(`${repository.provider.name} does not support releases`);
 }
-async function commitReleaseFiles(options, cwd, outputPath, versionPath, releaseExists) {
+async function commitReleaseFiles(options, cwd, outputPath, versionPath, releaseExists, tag) {
 	const releasePaths = [outputPath, versionPath].filter((path) => path !== void 0);
 	if (!(await git(cwd, "status", "--porcelain", "--", ...releasePaths)).trim()) return;
 	await git(cwd, "add", "--", ...releasePaths);
 	const versionChanges = versionPath ? await git(cwd, "status", "--porcelain", "--", versionPath) : "";
-	const commitMessage = versionPath && !versionChanges.trim() ? `docs(changelog): ${releaseExists ? "update" : "add"} v${options.version} release notes` : `chore(release): v${options.version}`;
+	const commitMessage = versionPath && !versionChanges.trim() ? `docs(changelog): ${releaseExists ? "update" : "add"} ${tag} release notes` : `chore(release): ${tag}`;
 	await git(cwd, ...resolveGitIdentity(options.author), "commit", "-m", commitMessage, ...options.author ? ["--author", options.author] : [], "--only", "--", ...releasePaths);
 }
 async function publishRelease(repository, release, token, preview, environment, manualAction = "create") {
@@ -435,6 +455,9 @@ function resolveOptions(versionArgument, options) {
 	if (!version) throw new Error(`Invalid release version: ${versionArgument}`);
 	const commit = options.commit ?? defaultConfig.cli.commit;
 	const release = options.release ?? defaultConfig.cli.release;
+	let tagPrefix = defaultConfig.cli.tagPrefix;
+	if (typeof options.tagPrefix === "string") tagPrefix = options.tagPrefix;
+	else if (options.tagPrefix === false) tagPrefix = "";
 	if (options.to !== void 0 && release) throw new Error("--to cannot be used with --release");
 	if (options.author !== void 0 && !commit && !release) throw new Error("--author requires --commit or --release");
 	if (!release && (options.name !== void 0 || options.draft !== void 0 || options.prerelease !== void 0)) throw new Error("--name, --draft, and --prerelease require --release");
@@ -449,6 +472,7 @@ function resolveOptions(versionArgument, options) {
 		release,
 		author: options.author ?? defaultConfig.cli.author,
 		token: options.token,
+		tagPrefix,
 		name: options.name,
 		draft: options.draft ?? defaultConfig.cli.draft,
 		prerelease: options.prerelease,
@@ -459,12 +483,19 @@ function resolveOptions(versionArgument, options) {
 }
 //#endregion
 //#region src/cli.ts
-const cli = cac("keepchanges").option("--from <ref>", "Start Git reference").option("--to <ref>", "End Git reference").option("--repository <source>", "Repository slug or URL").option("--output <path>", "Changelog file path").option("--dry", "Preview without modifying files or remotes").option("--commit", "Commit the changelog and version update").option("--release", "Publish a repository release").option("--author <author>", "Commit author in \"Name <email>\" format").option("-t, --token <token>", "Repository token").option("--name <name>", "Repository release name").option("-d, --draft", "Create a draft repository release").option("--prerelease", "Mark the repository release as prerelease").option("--emoji", "Use emojis in changelog section titles").option("--capitalize", "Capitalize changelog entries").option("--group", "Group repeated commit scopes");
-cli.command("[version]").usage("<version> [options]").action(async (versionArgument, options) => {
+const cli = cac("keepchanges").option("--from <ref>", "Start Git reference").option("--to <ref>", "End Git reference").option("--repository <source>", "Repository slug or URL").option("--output <path>", "Changelog file path").option("--dry", "Preview without modifying files or remotes").option("--commit", "Commit the changelog and version update").option("--release", "Publish a repository release").option("--author <author>", "Commit author in \"Name <email>\" format").option("-t, --token <token>", "Repository token").option("--no-tag-prefix", "Create version tags without a prefix").option("--tag-prefix <prefix>", "Prefix used for version tags", { default: defaultConfig.cli.tagPrefix }).option("--name <name>", "Repository release name").option("-d, --draft", "Create a draft repository release").option("--prerelease", "Mark the repository release as prerelease").option("--emoji", "Use emojis in changelog section titles").option("--capitalize", "Capitalize changelog entries").option("--group", "Group repeated commit scopes");
+cli.command("<version>").usage("<version> [options]").action(async (versionArgument, options) => {
 	await createChanges(resolveOptions(versionArgument, options), { cwd: process.cwd() });
 });
 cli.help();
 cli.version(version);
-cli.parse();
+try {
+	cli.parse(process.argv, { run: false });
+	await cli.runMatchedCommand();
+} catch (error) {
+	const message = error instanceof Error ? error.message : String(error);
+	process.stderr.write(`${message}\n`);
+	process.exitCode = 1;
+}
 //#endregion
 export {};

package/dist/{commit-FX77u6Sj.mjs → commit-DBopyhs1.mjs}

@@ -9,6 +9,7 @@ const defaultConfig = {
 		commit: false,
 		release: false,
 		author: "github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>",
+		tagPrefix: "v",
 		draft: false
 	},
 	changelog: {
@@ -59,7 +60,7 @@ function resolveChangelogConfig(overrides = {}) {
 function generateChangelog(options, overrides = {}) {
 	const config = resolveChangelogConfig(overrides);
 	const changes = [...renderSection(options.commits.filter((commit) => commit.isBreaking), config.breakingChanges, config, options.repository), ...Object.entries(config.types).flatMap(([type, section]) => renderSection(options.commits.filter((commit) => !commit.isBreaking && commit.type === type), section, config, options.repository))];
-	const body = [...changes.length ? changes : [`*${config.messages.noSignificantChanges}*`], ...options.repository && options.comparisonFrom ? ["", `##### &nbsp;&nbsp;&nbsp;&nbsp;[${config.messages.viewChanges.replace("{provider}", options.repository.provider.name)}](${options.repository.provider.compareUrl(options.repository, options.comparisonFrom, `v${options.version}`)})`] : []].join("\n").trim();
+	const body = [...changes.length ? changes : [`*${config.messages.noSignificantChanges}*`], ...options.repository && options.comparisonFrom ? ["", `##### &nbsp;&nbsp;&nbsp;&nbsp;[${config.messages.viewChanges.replace("{provider}", options.repository.provider.name)}](${options.repository.provider.compareUrl(options.repository, options.comparisonFrom, options.comparisonTo ?? `v${options.version}`)})`] : []].join("\n").trim();
 	return {
 		body,
 		release: [

package/dist/index.d.mts

@@ -90,6 +90,7 @@ interface KeepChangesConfig {
     commit: boolean;
     release: boolean;
     author: string;
+    tagPrefix: string;
     draft: boolean;
   };
   changelog: ChangelogConfig;
@@ -102,6 +103,7 @@ declare const defaultConfig: {
     commit: false;
     release: false;
     author: string;
+    tagPrefix: string;
     draft: false;
   };
   changelog: {
@@ -140,6 +142,7 @@ interface GenerateChangelogOptions {
   commits: Commit[];
   repository?: Repository;
   comparisonFrom?: string;
+  comparisonTo?: string;
 }
 interface GeneratedChangelog {
   body: string;

package/dist/index.mjs

@@ -1,2 +1,2 @@
-import { a as insertRelease, c as defaultConfig, i as hasRelease, l as resolveChangelogConfig, n as parseCommits, o as readChangelog, r as generateChangelog, s as writeChangelog, t as parseCommit } from "./commit-FX77u6Sj.mjs";
+import { a as insertRelease, c as defaultConfig, i as hasRelease, l as resolveChangelogConfig, n as parseCommits, o as readChangelog, r as generateChangelog, s as writeChangelog, t as parseCommit } from "./commit-DBopyhs1.mjs";
 export { defaultConfig, generateChangelog, hasRelease, insertRelease, parseCommit, parseCommits, readChangelog, resolveChangelogConfig, writeChangelog };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "keepchanges",
   "type": "module",
-  "version": "1.0.0-beta.3",
+  "version": "1.0.1",
   "description": "Generate and maintain CHANGELOG.md from Conventional Commits.",
   "author": "edram",
   "license": "MIT",