conventional-commits-parser 实战指南：把原始 Commit 消息解析为结构化对象的完整方案

开发工具CLI文档【免费下载链接】conventional-changelogGenerate changelogs and release notes from a projects commit messages and metadata.项目地址https://gitcode.com/gh_mirrors/co/conventional-changelog点击查看免费下载conventional-commits-parser是 conventional-changelog 工具链中负责读懂 commit的第一级流水线它把一条原始的 conventional commit 文本拆解为包含type、scope、subject、notes破坏性变更、referencesissue 引用、mentions等字段的纯 JS 对象。读完本文你将掌握它的三种入口 APICommitParser、parseCommits、parseCommitsStream、全部可配置解析选项及其默认值、CLI 用法以及从源码层面理解逐行解析状态机的工作方式从而为自己的 commit 规范定制解析器。它在整个 changelog 流水线中的位置从项目文档结构看changelog 生成遵循parser → filter → writer的三段式流水线parser 负责解析conventional-commits-filter负责过滤conventional-changelog-writer负责按模板写出。conventional-commits-parser输出的结构化对象正是后两级的直接输入顶层的 conventional-changelog 在读取项目提交历史时底层使用的也是它。原始 commit 数据通常来自 git例如conventional-changelog/git-client的getRawCommits()。相关文档入口包级说明packages/conventional-commits-parser/README.md在线文档仓库内 Markdown 源Introduction、JS API、CLI安装与快速上手该包是ESM-only、要求Node.js 22见 package.json 中的engines字段因此只能以import方式使用package.json中type: module且exports指向模块入口。# pnpm pnpm add conventional-commits-parser # yarn yarn add conventional-commits-parser # npm npm i conventional-commits-parser最基础的使用方式继承自 README 的示例import { CommitParser } from conventional-commits-parser const parser new CommitParser() const commit parser.parse( feat(scope): broadcast $destroy event on scope destruction\nCloses #1 ) console.log(commit)输出结构{ type: feat, scope: scope, subject: broadcast $destroy event on scope destruction, header: feat(scope): broadcast $destroy event on scope destruction, footer: Closes #1, references: [{ action: Closes, issue: 1, raw: #1, prefix: #, // owner、repository 等字段 }], // merge / revert / notes / mentions 等字段 }解析结果 Commit 对象解剖parse()返回的对象由 createCommitObject 初始化为固定的基础字段再按选项追加自定义字段。基础字段定义在 types.ts字段类型含义headerstring \| null提交信息第一行原始文本type、scope、subjectstring \| null由headerPattern捕获组按headerCorrespondence命名拆分出的头部mergestring \| null匹配到的 merge/PR 头配置mergePattern后bodystring \| null正文部分footerstring \| nullfooter 部分notes{ title, text }[]重要备注典型如破坏性变更referencesCommitReference[]issue 引用列表mentionsstring[]消息中的-mention 用户名revertRecordstring, string \| null \| nullrevert 提交被回退的目标字段其中references的每一项结构CommitReference字段说明raw原始引用文本如#42action引用动作关键词如Closes无则nullowner被引用的 ownerowner/repository形式时或nullrepository被引用的仓库名或nullissueissue 编号prefixissue 前缀如#除固定字段外Commit 对象还叠加了一个CommitMeta任意键值映射用于承载fieldPattern匹配出的自定义块字段——这解释了为什么console.log(commit)会出现文档中未列出的扩展键。解析原理parse() 的逐行状态机CommitParser.parse()的实现位于 CommitParser.ts整体流程可以概括为一条自上而下的消费行状态机预处理trimNewLines去除首尾空行按\r?\n切行若配置了commentChar还会用 truncateToScissor 截断 git 的剪刀线commentChar ------------------------ 8 ------------------------即git log中用于忽略 patch 的标记之后的内容并逐行过滤以commentChar开头的注释行同时gpgFilter会剔除gpg:签名行。parseMerge()若首行匹配mergePattern把该行记入commit.merge并按mergeCorrespondence命名捕获组随后 conventional 头部从下一行开始解析。parseHeader()优先用breakingHeaderPattern匹配头部再退回headerPattern匹配成功后通过 assignMatchedCorrespondence 把捕获组按headerCorrespondence默认[type, scope, subject]写入 commit。若正则使用了命名捕获组也可以直接用组名赋值。parseReferences()对 header、body、footer 中出现的文本反复匹配引用模式抽出action 前缀 issue如果文本里是 URL内置url正则则跳过避免把链接误判为引用。主循环逐行在仍有行可读时循环调用——parseMeta()匹配fieldPattern的-xxx-自定义块把块内行追加到commit[字段名]上parseNotes()当前行匹配notes正则由noteKeywords构造时开启一条 note 并持续吞入后续行直到遇到新的 note、meta 块或 footer tokenparseBodyAndFooter()其余行按是否命中footerToken正则归入body或footer并继续提取 references。收尾parseBreakingHeader()在头部命中breakingHeaderPattern且尚无 note 时把捕获内容补为一条BREAKING CHANGEnoteparseMentions()用硬编码的/([\w-])/g收集 提及见 regex.tsparseRevert()用revertPattern识别 revert 提交最后cleanupCommit()修剪 body/footer/notes 的空行并按action raw小写对 references去重。几个值得注意的判定细节footer 的判定遵循 git trailer 约定getFooterTokenRegex 生成的正则为^(?:BREAKING CHANGE|[\w-])(?::\s|\s(?:issuePrefixes)).忽略大小写即行首是单词 token后跟冒号或 issue 前缀才算 footer token缩进的key: value行不算 footer会继续留在 body 里。references 去重同一提交里重复出现相同的Closes #1只保留一次cleanupCommit。空输入直接抛错parse()对空白字符串抛TypeError(Expected a raw commit)。全部解析选项与默认值三个入口函数接受同一套选项默认值集中在 options.ts选项的类型与逐条说明见 types.ts选项类型默认值说明headerPatternRegExp/^(\w*)(?:\(([\w$.\-*/ ]*)\))?: (.*)$/匹配 conventional 头部并拆分捕获组headerCorrespondencestring[][type, scope, subject]头部捕获组的命名顺序与headerPattern捕获组一一对应breakingHeaderPatternRegExp无匹配破坏性变更头部如feat!: ...命中后生成BREAKING CHANGEnotemergePatternRegExp无匹配 merge/PR 头命中后下一行才作为 conventional 头部解析mergeCorrespondencestring[]无mergePattern捕获组命名revertPatternRegExp/^Revert\s([\s\S]*)\s*This reverts commit (\w*)\.?/匹配 revert 提交对应git revert生成的默认消息revertCorrespondencestring[][header, hash]revertPattern捕获组命名fieldPatternRegExp/^-(?.*\w)(.*?)-$/匹配 body 中的自定义-字段-块要求字段名至少含一个单词字符避免把 YAML 文档标记---误判为字段noteKeywords(string \| RegExp)[][BREAKING CHANGE, BREAKING-CHANGE]触发 note 的关键词忽略大小写notesPattern(text) RegExp无自定义 note 正则构造函数入参是关键词合并后的文本issuePrefixes(string \| RegExp)[][#]issue 前缀列表如gh-123中gh-即为前缀issuePrefixesCaseSensitivebooleanfalseissue 前缀是否区分大小写referenceActions(string \| RegExp)[]close、closes、closed、fix、fixes、fixed、resolve、resolves、resolved引用 issue 的动作关键词忽略大小写commentCharstring无注释符配置后启用注释过滤与剪刀线截断warnboolean \| (message) voidnoop仅parseCommits/parseCommitsStream有效true表示严格模式解析失败即抛出这些选项如何落地为正则可以在 regex.ts 中看到noteKeywords经joinOr合并字符串自动转义后拼成^(?:\*\s)?(关键词): (文本)形式的忽略大小写正则referenceActions生成(动作)(\s(.*?))(?下一个动作|$)的迭代匹配issuePrefixes生成引用片段正则(前缀)(issue 编号)编号字符集为[\w-]且以空白、行尾或,;.)]作为边界。一个来自项目文档的易错点默认headerPattern不捕获!破坏性语法——要识别feat!: ...这种头部简写需要显式传入breakingHeaderPattern或者在 footer 里写BREAKING CHANGE:仓库内的 preset如conventional-changelog-conventionalcommits会替你配好这些。批量解析parseCommits 与 parseCommitsStream单条解析用CommitParser处理整段提交历史典型来源是git-client的getRawCommits()时stream.ts 提供两个批量入口import { parseCommits, parseCommitsStream } from conventional-commits-parser import { pipeline } from node:stream/promises import { Readable } from node:stream // 方式一异步生成器函数配合 stream.pipeline await pipeline( rawCommits, parseCommits(options), async function* (commits) { for await (const commit of commits) { console.log(commit) } } ) // 方式二Node.js Transform 流 Readable.from(rawCommits) .pipe(parseCommitsStream()) .on(data, commit console.log(commit))两者的实现关系很直接parseCommitsStream(options)内部就是Transform.from(parseCommits(options))。parseCommits返回一个 async generator 函数遍历可迭代/异步可迭代的原始提交逐条调用CommitParser#parse解析失败时的行为由warn选项控制——默认静默跳过noop传true则立即抛出严格模式传函数则把错误字符串交给你的回调处理stream.ts。这也解释了为什么流式入口适合尽力而为地解析整段git log输出。CLI 用法package.json的publishConfig.bin声明了可执行命令conventional-commits-parser其实现位于 cli/index.ts。它的设计目标是练习写 commit 消息或从文件解析消息不带文件参数进入交互式 shell带参数则解析文件内容也可从 stdin 读取。Usage conventional-commits-parser [-s commit-separator] conventional-commits-parser [-s commit-separator] path [path ...] cat path | conventional-commits-parser [-s commit-separator] Example conventional-commits-parser conventional-commits-parser log.txt cat log.txt | conventional-commits-parser conventional-commits-parser log2.txt -s parsed.txtCLI 选项一览源码中的帮助文本 HELP选项说明-s, --separator提交之间的分隔符默认为三个换行\n\n\n-p, --header-pattern头部匹配正则-c, --header-correspondence逗号分隔的捕获组命名-r, --reference-actions逗号分隔的 issue 引用动作关键词-i, --issue-prefixes逗号分隔的 issue 前缀--issue-prefixes-case-sensitiveissue 前缀区分大小写-n, --note-keywords逗号分隔的 note 关键词-f, --field-pattern自定义字段块匹配正则--revert-patternrevert 匹配正则--revert-correspondence逗号分隔的 revert 字段命名-v, --verbose解析失败时打印警告而非静默命令行字符串到解析器选项的转换逻辑见 cli/options.ts正则类选项用new RegExp(...)构造列表类选项按逗号切分并去除空白-v开启时warn绑定console.warn未开启时 CLI 默认以严格模式warn: true运行即任何一条提交解析失败都会使命令以非零码退出。输入侧按指定文件 → TTY 交互 → stdin三种来源分流cli/index.ts再经pipeline(inputStream, parseCommits(options), stringify, process.stdout)完成解析与输出。仓库测试目录中的 log1.txt 等 fixture 就是这类文件的实际形态可用于对照 CLI 解析行为。定制解析器识别自定义前缀与动作如果你的仓库使用GH-17这类前缀或者用refs这样的动作词只需构造时传入选项即可import { CommitParser } from conventional-commits-parser const parser new CommitParser({ issuePrefixes: [#, GH-], referenceActions: [closes, fixes, refs] }) parser.parse(fix(api): handle timeouts\n\nrefs GH-17)此时references中会得到{ raw: GH-17, prefix: GH-, issue: 17, action: refs, ... }。类似地通过覆盖headerPattern/headerCorrespondence可以适配非标准头部通过noteKeywords可以追加企业自定义的破坏性变更标记词通过commentChar如#可以让解析器忽略git log --format...输出中携带的注释与8剪刀线内容。小结conventional-commits-parser以CommitParser#parse的逐行状态机为核心把自由文本的 commit 消息规范化为可被 filter、writer 直接消费的结构化对象parseCommits/parseCommitsStream提供了面向整段历史的流式批量能力与可配置的容错策略CLI 则提供了文件/stdin 解析与 commit 练习场景。所有行为——默认正则、捕获组命名、footer 判定、引用去重——都集中在 src/options.ts、src/regex.ts 与 src/CommitParser.ts 中行为细节可进一步对照 CommitParser.spec.ts 与 stream.spec.ts 的测试用例验证。赞分享开发工具CLI文档【免费下载链接】conventional-changelogGenerate changelogs and release notes from a projects commit messages and metadata.项目地址https://gitcode.com/gh_mirrors/co/conventional-changelog点击查看免费下载相关推荐caveman-commit为 feishin 生成精炼 Conventional Commits 提交信息的 Agent Skill 实战指南caveman commit为 feishin 生成精炼 Conventional Commits 提交信息的 Agent Skill 实战指南 本篇指南围绕桌面应用音视频前端RedisInsight 提交信息规范实战基于 Conventional Commits 的 Commit Message 编写指南RedisInsight 提交信息规范实战基于 Conventional Commits 的 Commit Message 编写指南 本文以 RedisIns数据库客户端桌面应用后端前端数据可视化Feishin 提交信息规范实战caveman-commit 技能与 Conventional Commits 落地指南Feishin 提交信息规范实战caveman commit 技能与 Conventional Commits 落地指南 导读 本文以 Feishin一款现桌面应用音视频前端上一篇如何在Joplin中配置VSCode作为外部编辑器完整指南下一篇Odoo测试自动化终极指南pytest单元测试与端到端测试框架详解 创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考