Ghostty 提交信息规范详解subsystem 前缀、参考引用与长描述的完整实践【免费下载链接】ghostty Ghostty is a fast, feature-rich, and cross-platform terminal emulator that uses platform-native UI and GPU acceleration.项目地址: https://gitcode.com/GitHub_Trending/gh/ghostty本文以 Ghostty 仓库中为 AI Agent 编写的提交信息技能文档 SKILL.md 为主体完整拆解其提交信息格式模板、主题行/引用/长描述三段式规则与落地工作流并结合仓库真实提交历史验证这些约定在 Ghostty 中的实际执行情况。读完本篇后你可以按照与 Ghostty 维护者一致的风格撰写可审计、可检索的提交信息并理解每一条规则背后的工程动机。规范文档的定位.agents/skills/writing-commit-messages/SKILL.md是 Ghostty 仓库内置的一份 Agent 技能skill文档文档头部的 frontmatter 声明了触发条件name: writing-commit-messages description: - Writes Git commit messages. Activates when the user asks to write a commit message, draft a commit message, or similar.也就是说当用户要求“写一条提交信息 / 起草一条提交信息”时执行环境会激活该技能并要求产出的提交信息严格遵循本文所述的风格。它的核心目标用原文一句话概括Write commit messages that follow commit style guidelines for the project——提交信息不是随手写的说明而是带有项目专属约定subsystem 前缀、行宽、语气的结构化产物。值得注意的是这份规范是 VCS 无关的它不假设仓库一定用 git而是根据工作区中是否存在.jj目录Jujutsu 版本控制的工作目录标记来决定使用git还是jj执行命令这一点在文末的工作流部分会完整展开。提交信息的三段式格式模板文档给出的标准格式由三部分按顺序组成中间以空行分隔subsystem: summary reference issues/PRs/etc. long form description对应地一条完整的 Ghostty 风格提交信息由主题行subsystem: summary形式独占首行引用区可选关联的 issue / PR / 讨论编号每行一个长描述可选纯散文式的正文解释改动内容、先前行为与新行为。三个部分之间各用一个空行分隔当引用区不存在时空行也要一并省略后文“引用区规则”中有明确说明。主题行规则subsystem 前缀与 summarysubsystem 前缀的确定方式主题行以小写的 subsystem 标识开头后跟冒号和空格。文档明确给出的前缀示例包括terminal、vt、lib、config、font并规定了三条特殊映射改动范围使用的前缀改动涉及 macOS 应用macos改动涉及 GTK 应用运行时gtk改动涉及构建系统build前缀的判定依据是diff 中变更的文件路径而不是主观印象。当改动范围更聚焦时允许使用/分隔的嵌套 subsystem条件是“helpful and exclusive”有帮助且独占文档给出的例子是terminal/osc。对照当前仓库的目录结构这些前缀与实际代码位置的对应关系非常清晰前缀对应的仓库路径terminalsrc/terminal/如 Terminal.zig、Screen.zigterminal/oscsrc/terminal/osc/terminal/kittysrc/terminal/kitty/terminal/csrc/terminal/c/libghosttyC API 层如 include/ghostty.h 与 src/main_c.zigmacosmacos/Swift 应用源码位于 macos/Sources/gtksrc/apprt/gtk/buildbuild.zig、Makefileci.github/workflows/ 下的工作流文件renderersrc/renderer/fontsrc/font/configsrc/config/i18npo/ 下的翻译文件从最近 400 条提交的主题行统计来看前缀分布与仓库结构高度吻合terminal:56 次、terminal/kitty:45 次、libghostty:30 次、macos/macOS合计约 57 次、i18n:14 次、renderer:8 次、gtk:6 次、ci:与build:各 5 次是最高频的前缀此外还出现了example:、deps:、font:、input:、termio:等按目录划分的子系统。可以看到前缀体系本质上就是把仓库的目录树压缩进提交历史让git log --oneline本身就成了一份带作用域过滤功能的项目导航。summary 的书写要求文档对冒号后面的 summary 部分提出三条硬性约束首字母小写不以大写开头祈使语气imperative mood如fix ...、add ...、update ...行尾不加句号。此外要求整体简洁整个主题行含 subsystem 前缀最好控制在 60 个字符以内。这条限制与git log --oneline的默认展示宽度一致目的是保证在终端里单行完整可见。仓库历史中的实际提交普遍遵守了这一点例如gtk: do not warn when gtk-xft-dpi is -1 font: update embedded Noto emoji fonts renderer: vsync unfocused surfaces while dirty引用区规则何时写、怎么写当改动与某个 GitHub issue、PR 或讨论相关时引用区必须出现在主题行之后格式要求是相关编号每行一个例如#1234引用区与主题行之间、与长描述之间各有一个空行。文档同时给出了一条容易忽视的反向规则如果没有引用就整个省略该段连空行也不要留下——即不允许出现“主题行后连续两个空行再接正文”的形态。这一点保证了提交信息在git log中的紧凑性。真实提交中引用区与长描述的组合形态可以参考这条修复RefCountedSet的提交c2906398bterminal: fix living item over-count in RefCountedSet.addWithId (#14081) Reported in https://github.com/ghostty-org/ghostty/discussions/14064 I validated this myself manually. The zero-ref branch of addWithIdContext incremented living unconditionally ...主题行末尾内联了 PR 号合并时的标准形态正文首行补充了报告来源随后直接进入技术描述。长描述规则散文、72 字符与 why/how对长描述部分文档给出了五条规则每一条都针对提交信息中常见的坏味道说明三件事什么变了what changed、之前的行为是什么what the previous behavior was、新行为如何工作how the new behavior works且都停留在高层描述用纯散文plain prose不用要点列表——提交正文不是 markdown 清单行宽约 72 字符换行与patch/邮件投递格式的传统保持一致聚焦 why 与 how而不是复述 diff——读者自己能看到 diff正文的价值在于解释动机与机制语气直接、技术化、不带填充词篇幅控制在“a handful of paragraphs; less is more”。用上面那条RefCountedSet提交逐段对照可以看到规则是如何落地的I validated this myself manually. The zero-ref branch ofaddWithIdContextincrementedlivingunconditionally even ifupsertresolved the value to an item that was already alive under a different ID.这一段回答的是“先前行为”——零引用分支无条件递增living接下来一段解释新行为与下游影响count()漂移、样式内存过量预留、未发现崩溃段落全部为散文行宽严格控制在 72 字符附近没有 bullet没有“本次提交修复了一个 bug”之类的填充语。另一条terminal/kitty: validate POSIX shared memory names的提交则在正文中说明改动是对新规格new spec的跟进属于典型的“聚焦 why 而非复述 diff”。工作流从 diff 到提交落盘文档末尾的 Workflow 一节规定了撰写提交信息的六步操作顺序检查.jj目录若存在则所有命令使用jj代替git执行当前仓库克隆中不含.jj目录因此默认走git路径。这条规则使同一份规范可以同时服务 git 用户与 Jujutsu 用户运行 diff查看自上次提交以来的全部变更如git diff/jj diff识别 subsystem根据变更文件的路径确定前缀对应前文的前缀映射表;识别引用从 diff 上下文或分支名中提取关联的 issue/PR 编号例如分支add-serbian-translation对应提交历史中的塞尔维亚语翻译系列提交按格式起草套用三段式模板写出完整提交信息应用提交但不推送Dont push the commit; leave that to the user——推送与否的决定权始终留给用户。这个流程刻意把“识别 subsystem”放在“识别引用”之前与格式模板中主题行先于引用区的顺序保持一致最后一步的“不推送”则与提交信息技能的定位相符它负责把本次变更准确、规范地固化为一条提交而不越权执行远端操作。对照真实历史的验证以下均取自当前仓库最近的实际提交可直接用git log复核覆盖规范中提到的大部分子系统实际提交主题行覆盖的规范点terminal: fix living item over-count in RefCountedSet.addWithId (#14081)嵌套修复语义 内联 PR 号 长描述terminal/kitty: validate POSIX shared memory names (#14080)嵌套 subsystemterminal/kittyterminal/c: allow freeing a search and its terminal in any orderC API 子层前缀terminal/clibghostty: add terminal search API (#14097)C API 门面层前缀libghosttygtk: do not warn when gtk-xft-dpi is -1 (#14085)GTK 应用运行时前缀gtkrenderer: vsync unfocused surfaces while dirty (#14068)renderer前缀build: update Sparkle to 2.9.6 and pin SPM (#14082)构建系统前缀buildci: require freestanding libghostty-vt buildsCI 工作流前缀cii18n: adjust and extend Ukrainian translation (#13854)翻译资产前缀i18n→po/font: update embedded Noto emoji fonts (#14047)font前缀其中ci: require freestanding libghostty-vt builds只有主题行、没有正文说明短小且自解释的变更可以合法地省略长描述——“less is more”并非要求每段都写满而是写出来的部分要信息密度足够。小结一份可直接执行的检查清单综合 SKILL.md 的完整内容与仓库实践撰写一条 Ghostty 风格提交信息前可以逐项核对主题行是否形如subsystem: summary前缀取自 diff 涉及的路径macos/gtk/build按约定映射聚焦时可用terminal/osc式嵌套summary 是否小写开头、祈使语气、行尾无句号且主题行总长在 60 字符内有引用时编号是否每行一个且与前后各隔一空行无引用时是否连同空行一起省略长描述是否用散文讲清“改了什么 / 之前什么样 / 现在如何工作”约 72 字符换行聚焦 why 与 how执行链路上是否先 diff、再定前缀、再找引用提交后未推送、推送留给用户这套规范的价值在于它把“提交信息”从自由文本变成了与仓库目录结构一一对应的、可被git log按前缀过滤的索引层前缀即作用域引用区即变更溯源长描述即行为说明。对贡献者而言照此执行即可让自己的提交与 Ghostty 现有历史保持风格一致对 Agent 而言这份 skill 文档提供了无歧义的格式契约与操作顺序使自动生成的提交信息在合入前就满足项目惯例。【免费下载链接】ghostty Ghostty is a fast, feature-rich, and cross-platform terminal emulator that uses platform-native UI and GPU acceleration.项目地址: https://gitcode.com/GitHub_Trending/gh/ghostty创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Ghostty 提交信息规范详解：subsystem 前缀、参考引用与长描述的完整实践
Ghostty 提交信息规范详解subsystem 前缀、参考引用与长描述的完整实践【免费下载链接】ghostty Ghostty is a fast, feature-rich, and cross-platform terminal emulator that uses platform-native UI and GPU acceleration.项目地址: https://gitcode.com/GitHub_Trending/gh/ghostty本文以 Ghostty 仓库中为 AI Agent 编写的提交信息技能文档 SKILL.md 为主体完整拆解其提交信息格式模板、主题行/引用/长描述三段式规则与落地工作流并结合仓库真实提交历史验证这些约定在 Ghostty 中的实际执行情况。读完本篇后你可以按照与 Ghostty 维护者一致的风格撰写可审计、可检索的提交信息并理解每一条规则背后的工程动机。规范文档的定位.agents/skills/writing-commit-messages/SKILL.md是 Ghostty 仓库内置的一份 Agent 技能skill文档文档头部的 frontmatter 声明了触发条件name: writing-commit-messages description: - Writes Git commit messages. Activates when the user asks to write a commit message, draft a commit message, or similar.也就是说当用户要求“写一条提交信息 / 起草一条提交信息”时执行环境会激活该技能并要求产出的提交信息严格遵循本文所述的风格。它的核心目标用原文一句话概括Write commit messages that follow commit style guidelines for the project——提交信息不是随手写的说明而是带有项目专属约定subsystem 前缀、行宽、语气的结构化产物。值得注意的是这份规范是 VCS 无关的它不假设仓库一定用 git而是根据工作区中是否存在.jj目录Jujutsu 版本控制的工作目录标记来决定使用git还是jj执行命令这一点在文末的工作流部分会完整展开。提交信息的三段式格式模板文档给出的标准格式由三部分按顺序组成中间以空行分隔subsystem: summary reference issues/PRs/etc. long form description对应地一条完整的 Ghostty 风格提交信息由主题行subsystem: summary形式独占首行引用区可选关联的 issue / PR / 讨论编号每行一个长描述可选纯散文式的正文解释改动内容、先前行为与新行为。三个部分之间各用一个空行分隔当引用区不存在时空行也要一并省略后文“引用区规则”中有明确说明。主题行规则subsystem 前缀与 summarysubsystem 前缀的确定方式主题行以小写的 subsystem 标识开头后跟冒号和空格。文档明确给出的前缀示例包括terminal、vt、lib、config、font并规定了三条特殊映射改动范围使用的前缀改动涉及 macOS 应用macos改动涉及 GTK 应用运行时gtk改动涉及构建系统build前缀的判定依据是diff 中变更的文件路径而不是主观印象。当改动范围更聚焦时允许使用/分隔的嵌套 subsystem条件是“helpful and exclusive”有帮助且独占文档给出的例子是terminal/osc。对照当前仓库的目录结构这些前缀与实际代码位置的对应关系非常清晰前缀对应的仓库路径terminalsrc/terminal/如 Terminal.zig、Screen.zigterminal/oscsrc/terminal/osc/terminal/kittysrc/terminal/kitty/terminal/csrc/terminal/c/libghosttyC API 层如 include/ghostty.h 与 src/main_c.zigmacosmacos/Swift 应用源码位于 macos/Sources/gtksrc/apprt/gtk/buildbuild.zig、Makefileci.github/workflows/ 下的工作流文件renderersrc/renderer/fontsrc/font/configsrc/config/i18npo/ 下的翻译文件从最近 400 条提交的主题行统计来看前缀分布与仓库结构高度吻合terminal:56 次、terminal/kitty:45 次、libghostty:30 次、macos/macOS合计约 57 次、i18n:14 次、renderer:8 次、gtk:6 次、ci:与build:各 5 次是最高频的前缀此外还出现了example:、deps:、font:、input:、termio:等按目录划分的子系统。可以看到前缀体系本质上就是把仓库的目录树压缩进提交历史让git log --oneline本身就成了一份带作用域过滤功能的项目导航。summary 的书写要求文档对冒号后面的 summary 部分提出三条硬性约束首字母小写不以大写开头祈使语气imperative mood如fix ...、add ...、update ...行尾不加句号。此外要求整体简洁整个主题行含 subsystem 前缀最好控制在 60 个字符以内。这条限制与git log --oneline的默认展示宽度一致目的是保证在终端里单行完整可见。仓库历史中的实际提交普遍遵守了这一点例如gtk: do not warn when gtk-xft-dpi is -1 font: update embedded Noto emoji fonts renderer: vsync unfocused surfaces while dirty引用区规则何时写、怎么写当改动与某个 GitHub issue、PR 或讨论相关时引用区必须出现在主题行之后格式要求是相关编号每行一个例如#1234引用区与主题行之间、与长描述之间各有一个空行。文档同时给出了一条容易忽视的反向规则如果没有引用就整个省略该段连空行也不要留下——即不允许出现“主题行后连续两个空行再接正文”的形态。这一点保证了提交信息在git log中的紧凑性。真实提交中引用区与长描述的组合形态可以参考这条修复RefCountedSet的提交c2906398bterminal: fix living item over-count in RefCountedSet.addWithId (#14081) Reported in https://github.com/ghostty-org/ghostty/discussions/14064 I validated this myself manually. The zero-ref branch of addWithIdContext incremented living unconditionally ...主题行末尾内联了 PR 号合并时的标准形态正文首行补充了报告来源随后直接进入技术描述。长描述规则散文、72 字符与 why/how对长描述部分文档给出了五条规则每一条都针对提交信息中常见的坏味道说明三件事什么变了what changed、之前的行为是什么what the previous behavior was、新行为如何工作how the new behavior works且都停留在高层描述用纯散文plain prose不用要点列表——提交正文不是 markdown 清单行宽约 72 字符换行与patch/邮件投递格式的传统保持一致聚焦 why 与 how而不是复述 diff——读者自己能看到 diff正文的价值在于解释动机与机制语气直接、技术化、不带填充词篇幅控制在“a handful of paragraphs; less is more”。用上面那条RefCountedSet提交逐段对照可以看到规则是如何落地的I validated this myself manually. The zero-ref branch ofaddWithIdContextincrementedlivingunconditionally even ifupsertresolved the value to an item that was already alive under a different ID.这一段回答的是“先前行为”——零引用分支无条件递增living接下来一段解释新行为与下游影响count()漂移、样式内存过量预留、未发现崩溃段落全部为散文行宽严格控制在 72 字符附近没有 bullet没有“本次提交修复了一个 bug”之类的填充语。另一条terminal/kitty: validate POSIX shared memory names的提交则在正文中说明改动是对新规格new spec的跟进属于典型的“聚焦 why 而非复述 diff”。工作流从 diff 到提交落盘文档末尾的 Workflow 一节规定了撰写提交信息的六步操作顺序检查.jj目录若存在则所有命令使用jj代替git执行当前仓库克隆中不含.jj目录因此默认走git路径。这条规则使同一份规范可以同时服务 git 用户与 Jujutsu 用户运行 diff查看自上次提交以来的全部变更如git diff/jj diff识别 subsystem根据变更文件的路径确定前缀对应前文的前缀映射表;识别引用从 diff 上下文或分支名中提取关联的 issue/PR 编号例如分支add-serbian-translation对应提交历史中的塞尔维亚语翻译系列提交按格式起草套用三段式模板写出完整提交信息应用提交但不推送Dont push the commit; leave that to the user——推送与否的决定权始终留给用户。这个流程刻意把“识别 subsystem”放在“识别引用”之前与格式模板中主题行先于引用区的顺序保持一致最后一步的“不推送”则与提交信息技能的定位相符它负责把本次变更准确、规范地固化为一条提交而不越权执行远端操作。对照真实历史的验证以下均取自当前仓库最近的实际提交可直接用git log复核覆盖规范中提到的大部分子系统实际提交主题行覆盖的规范点terminal: fix living item over-count in RefCountedSet.addWithId (#14081)嵌套修复语义 内联 PR 号 长描述terminal/kitty: validate POSIX shared memory names (#14080)嵌套 subsystemterminal/kittyterminal/c: allow freeing a search and its terminal in any orderC API 子层前缀terminal/clibghostty: add terminal search API (#14097)C API 门面层前缀libghosttygtk: do not warn when gtk-xft-dpi is -1 (#14085)GTK 应用运行时前缀gtkrenderer: vsync unfocused surfaces while dirty (#14068)renderer前缀build: update Sparkle to 2.9.6 and pin SPM (#14082)构建系统前缀buildci: require freestanding libghostty-vt buildsCI 工作流前缀cii18n: adjust and extend Ukrainian translation (#13854)翻译资产前缀i18n→po/font: update embedded Noto emoji fonts (#14047)font前缀其中ci: require freestanding libghostty-vt builds只有主题行、没有正文说明短小且自解释的变更可以合法地省略长描述——“less is more”并非要求每段都写满而是写出来的部分要信息密度足够。小结一份可直接执行的检查清单综合 SKILL.md 的完整内容与仓库实践撰写一条 Ghostty 风格提交信息前可以逐项核对主题行是否形如subsystem: summary前缀取自 diff 涉及的路径macos/gtk/build按约定映射聚焦时可用terminal/osc式嵌套summary 是否小写开头、祈使语气、行尾无句号且主题行总长在 60 字符内有引用时编号是否每行一个且与前后各隔一空行无引用时是否连同空行一起省略长描述是否用散文讲清“改了什么 / 之前什么样 / 现在如何工作”约 72 字符换行聚焦 why 与 how执行链路上是否先 diff、再定前缀、再找引用提交后未推送、推送留给用户这套规范的价值在于它把“提交信息”从自由文本变成了与仓库目录结构一一对应的、可被git log按前缀过滤的索引层前缀即作用域引用区即变更溯源长描述即行为说明。对贡献者而言照此执行即可让自己的提交与 Ghostty 现有历史保持风格一致对 Agent 而言这份 skill 文档提供了无歧义的格式契约与操作顺序使自动生成的提交信息在合入前就满足项目惯例。【免费下载链接】ghostty Ghostty is a fast, feature-rich, and cross-platform terminal emulator that uses platform-native UI and GPU acceleration.项目地址: https://gitcode.com/GitHub_Trending/gh/ghostty创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考