gh-commit
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseSmart Git Commit
智能Git提交
Create well-formatted commit: $ARGUMENTS
创建规范格式的提交:$ARGUMENTS
Current Repository State
当前仓库状态
- Git status: !
git status --porcelain - Current branch: !
git branch --show-current - Staged changes: !
git diff --cached --stat - Unstaged changes: !
git diff --stat - Recent commits: !
git log --oneline -5
- Git状态:!
git status --porcelain - 当前分支:!
git branch --show-current - 已暂存的更改:!
git diff --cached --stat - 未暂存的更改:!
git diff --stat - 最近提交:!
git log --oneline -5
What This Command Does
该命令的功能
- Checks which files are staged with
git status - If 0 files are staged, automatically adds all modified and new files with
git add - Performs a to understand what changes are being committed
git diff - Analyzes the diff to determine if multiple distinct logical changes are present
- If multiple distinct changes are detected, suggests breaking the commit into multiple smaller commits
- For each commit (or the single commit if not split), creates a commit message using conventional commit format
- 使用检查哪些文件已被暂存
git status - 如果暂存区文件数为0,自动使用添加所有已修改和新增的文件
git add - 执行了解要提交的具体更改内容
git diff - 分析diff内容,判断是否存在多个独立的逻辑更改
- 如果检测到多个独立更改,建议将提交拆分为多个更小的提交
- 针对每个提交(如果不拆分则为单个提交),使用约定式提交格式生成提交信息
Best Practices for Commits
提交最佳实践
- Follow the Conventional Commits specification as described below.
- 遵循下文所述的Conventional Commits规范。
Conventional Commits 1.0.0
约定式提交(Conventional Commits)1.0.0
Summary
概述
The Conventional Commits specification is a lightweight convention on top of commit messages. It provides an easy set of rules for creating an explicit commit history; which makes it easier to write automated tools on top of. This convention dovetails with SemVer, by describing the features, fixes, and breaking changes made in commit messages.
The commit message should be structured as follows:
<type>[optional scope]: <description>
[optional body]
[optional footer(s)]The commit contains the following structural elements, to communicate intent to the consumers of your library:
- fix: a commit of the type patches a bug in your codebase (this correlates with
fixin Semantic Versioning).PATCH - feat: a commit of the type introduces a new feature to the codebase (this correlates with
featin Semantic Versioning).MINOR - BREAKING CHANGE: a commit that has a footer , or appends a
BREAKING CHANGE:after the type/scope, introduces a breaking API change (correlating with'!'in Semantic Versioning). A BREAKING CHANGE can be part of commits of any type.MAJOR - types other than and
fix:are allowed, for example @commitlint/config-conventional (based on the Angular convention) recommendsfeat:,build:,chore:,ci:,docs:,style:,refactor:,perf:, and others.test: - footers other than may be provided and follow a convention similar to git trailer format.
BREAKING CHANGE: <description>
Additional types are not mandated by the Conventional Commits specification, and have no implicit effect in Semantic Versioning (unless they include a BREAKING CHANGE). A scope may be provided to a commit's type, to provide additional contextual information and is contained within parenthesis, e.g., .
feat(parser): add ability to parse arrays约定式提交规范是建立在提交信息之上的轻量约定。它提供了一套简单的规则来创建清晰的提交历史,从而便于在其上构建自动化工具。这套约定与SemVer相契合,会在提交信息中描述新增功能、问题修复以及破坏性变更。
提交信息的结构应如下所示:
<type>[optional scope]: <description>
[optional body]
[optional footer(s)]提交包含以下结构元素,用于向库的使用者传达变更意图:
- fix: 类型为的提交表示在代码库中修复了一个bug(这对应语义化版本中的
fix版本)。PATCH - feat: 类型为的提交表示向代码库中新增了一个功能(这对应语义化版本中的
feat版本)。MINOR - BREAKING CHANGE: 页脚包含,或者在类型/范围后附加
BREAKING CHANGE:的提交,表示引入了破坏性API变更(对应语义化版本中的'!'版本)。破坏性变更可以是任意类型提交的一部分。MAJOR - 除了和
fix:之外也允许使用其他类型,例如@commitlint/config-conventional(基于Angular约定)推荐的feat:、build:、chore:、ci:、docs:、style:、refactor:、perf:等。test: - 除了之外也可以提供其他页脚,遵循与git trailer格式类似的约定。
BREAKING CHANGE: <description>
约定式提交规范不强制要求使用额外的类型,且这些类型在语义化版本中也没有隐式影响(除非包含破坏性变更)。你可以在提交类型后添加范围,用来提供额外的上下文信息,范围需要放在括号内,例如:。
feat(parser): add ability to parse arraysExamples
示例
Commit message with description and breaking change footer
包含描述和破坏性变更页脚的提交信息
feat: allow provided config object to extend other configs
BREAKING CHANGE: `extends` key in config file is now used for extending other config filesfeat: allow provided config object to extend other configs
BREAKING CHANGE: `extends` key in config file is now used for extending other config filesCommit message with '!'
to draw attention to breaking change
'!'使用'!'
标注的破坏性变更提交信息
'!'feat'!': send an email to the customer when a product is shippedfeat'!': send an email to the customer when a product is shippedCommit message with scope and '!'
to draw attention to breaking change
'!'带范围且使用'!'
标注的破坏性变更提交信息
'!'feat(api)'!': send an email to the customer when a product is shippedfeat(api)'!': send an email to the customer when a product is shippedCommit message with both '!'
and BREAKING CHANGE footer
'!'同时包含'!'
和破坏性变更页脚的提交信息
'!'chore'!': drop support for Node 6
BREAKING CHANGE: use JavaScript features not available in Node 6.chore'!': drop support for Node 6
BREAKING CHANGE: use JavaScript features not available in Node 6.Commit message with no body
无正文的提交信息
docs: correct spelling of CHANGELOGdocs: correct spelling of CHANGELOGCommit message with scope
带范围的提交信息
feat(lang): add Polish languagefeat(lang): add Polish languageCommit message with multi-paragraph body and multiple footers
包含多段正文和多个页脚的提交信息
fix: prevent racing of requests
Introduce a request id and a reference to latest request. Dismiss
incoming responses other than from latest request.
Remove timeouts which were used to mitigate the racing issue but are
obsolete now.
Reviewed-by: Z
Refs: #123fix: prevent racing of requests
Introduce a request id and a reference to latest request. Dismiss
incoming responses other than from latest request.
Remove timeouts which were used to mitigate the racing issue but are
obsolete now.
Reviewed-by: Z
Refs: #123Specification
规范
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.
- Commits MUST be prefixed with a type, which consists of a noun, ,
feat, etc., followed by the OPTIONAL scope, OPTIONALfix, and REQUIRED terminal colon and space.'!' - The type MUST be used when a commit adds a new feature to your application or library.
feat - The type MUST be used when a commit represents a bug fix for your application.
fix - A scope MAY be provided after a type. A scope MUST consist of a noun describing a section of the codebase surrounded by parenthesis, e.g.,
fix(parser): - A description MUST immediately follow the colon and space after the type/scope prefix. The description is a short summary of the code changes, e.g., fix: array parsing issue when multiple spaces were contained in string.
- A longer commit body MAY be provided after the short description, providing additional contextual information about the code changes. The body MUST begin one blank line after the description.
- A commit body is free-form and MAY consist of any number of newline separated paragraphs.
- One or more footers MAY be provided one blank line after the body. Each footer MUST consist of a word token, followed by either a or
:<space>separator, followed by a string value (this is inspired by the git trailer convention).<space># - A footer's token MUST use in place of whitespace characters, e.g.,
-(this helps differentiate the footer section from a multi-paragraph body). An exception is made forAcked-by, which MAY also be used as a token.BREAKING CHANGE - A footer's value MAY contain spaces and newlines, and parsing MUST terminate when the next valid footer token/separator pair is observed.
- Breaking changes MUST be indicated in the type/scope prefix of a commit, or as an entry in the footer.
- If included as a footer, a breaking change MUST consist of the uppercase text BREAKING CHANGE, followed by a colon, space, and description, e.g., BREAKING CHANGE: environment variables now take precedence over config files.
- If included in the type/scope prefix, breaking changes MUST be indicated by a immediately before the
'!'. If:is used,'!'MAY be omitted from the footer section, and the commit description SHALL be used to describe the breaking change.BREAKING CHANGE: - Types other than and
featMAY be used in your commit messages, e.g., docs: update ref docs.fix - The units of information that make up Conventional Commits MUST NOT be treated as case sensitive by implementors, with the exception of BREAKING CHANGE which MUST be uppercase.
- BREAKING-CHANGE MUST be synonymous with BREAKING CHANGE, when used as a token in a footer.
本文档中的关键词“必须(MUST)”、“禁止(MUST NOT)”、“要求(REQUIRED)”、“应当(SHALL)”、“不应(SHALL NOT)”、“应该(SHOULD)”、“不应该(SHOULD NOT)”、“推荐(RECOMMENDED)”、“可以(MAY)”和“可选(OPTIONAL)”需按照RFC 2119中的描述进行解释。
- 提交必须以类型为前缀,类型由、
feat等名词组成,后接可选的范围、可选的fix,以及必填的冒号和空格。'!' - 当提交为应用或库新增功能时,必须使用类型。
feat - 当提交代表应用的bug修复时,必须使用类型。
fix - 可以在类型后添加范围。范围必须是描述代码库模块的名词,包裹在括号内,例如
fix(parser): - 描述必须紧跟在类型/范围前缀后的冒号和空格之后。描述是代码变更的简短总结,例如:。
fix: array parsing issue when multiple spaces were contained in string - 可以在简短描述之后添加更长的提交正文,提供与代码变更相关的额外上下文信息。正文必须在描述之后空一行开始。
- 提交正文为自由格式,可以包含任意数量的换行分隔段落。
- 可以在正文之后空一行添加一个或多个页脚。每个页脚必须由一个单词标记组成,后接或
:<空格>分隔符,再接字符串值(这一设计灵感来自git trailer约定)。<空格># - 页脚的标记必须使用代替空白字符,例如
-(这有助于区分页脚部分和多段正文)。Acked-by是例外,也可以作为标记使用。BREAKING CHANGE - 页脚的值可以包含空格和换行,当检测到下一个有效的页脚标记/分隔符对时,解析必须终止。
- 破坏性变更必须在提交的类型/范围前缀中标注,或者作为页脚中的条目存在。
- 如果作为页脚包含,破坏性变更必须由大写文本BREAKING CHANGE组成,后接冒号、空格和描述,例如:。
BREAKING CHANGE: environment variables now take precedence over config files - 如果包含在类型/范围前缀中,破坏性变更必须由紧跟在之前的
:标注。如果使用了'!',可以省略页脚部分的'!',提交描述应当用来描述破坏性变更。BREAKING CHANGE: - 可以在提交信息中使用和
feat之外的类型,例如:fixdocs: update ref docs. - 实现工具不得将构成约定式提交的信息单元视为区分大小写的,唯一例外是BREAKING CHANGE必须为大写。
- 当在页脚中作为标记使用时,BREAKING-CHANGE必须与BREAKING CHANGE同义。
Why Use Conventional Commits
为什么使用约定式提交?
- Automatically generating CHANGELOGs.
- Automatically determining a semantic version bump (based on the types of commits landed).
- Communicating the nature of changes to teammates, the public, and other stakeholders.
- Triggering build and publish processes.
- Making it easier for people to contribute to your projects, by allowing them to explore a more structured commit history.
- 自动生成CHANGELOG
- 基于提交类型自动确定语义化版本号升级幅度
- 向团队成员、公众和其他利益相关者传达变更性质
- 触发构建和发布流程
- 通过更结构化的提交历史,降低人们参与项目贡献的门槛
FAQ
常见问题
How should I deal with commit messages in the initial development phase?
初始开发阶段应该如何处理提交信息?
We recommend that you proceed as if you've already released the product. Typically somebody, even if it's your fellow software developers, is using your software. They'll want to know what's fixed, what breaks etc.
我们建议你按照已经发布产品的方式执行。通常总会有人在使用你的软件,哪怕是你的开发同事,他们也会想知道什么问题被修复了、什么功能出现了破坏性变更等。
Are the types in the commit title uppercase or lowercase?
提交标题中的类型应该大写还是小写?
Any casing may be used, but it's best to be consistent.
任意大小写都可以,但最好保持一致。
What do I do if the commit conforms to more than one of the commit types?
如果提交符合多个提交类型怎么办?
Go back and make multiple commits whenever possible. Part of the benefit of Conventional Commits is its ability to drive us to make more organized commits and PRs.
尽可能返回拆分出多个提交。约定式提交的优势之一就是能够推动我们生成更有条理的提交和PR。
Doesn't this discourage rapid development and fast iteration?
这会不会阻碍快速开发和快速迭代?
It discourages moving fast in a disorganized way. It helps you be able to move fast long term across multiple projects with varied contributors.
它阻碍的是杂乱无章的快速推进。从长期来看,它能帮助你在有不同贡献者参与的多个项目中实现高效推进。
Might Conventional Commits lead developers to limit the type of commits they make because they'll be thinking in the types provided?
约定式提交会不会让开发者受限在提供的类型中,从而限制他们的提交类型?
Conventional Commits encourages us to make more of certain types of commits such as fixes. Other than that, the flexibility of Conventional Commits allows your team to come up with their own types and change those types over time.
约定式提交鼓励我们生成更多特定类型的提交,例如修复类提交。除此之外,约定式提交的灵活性允许你的团队制定自己的类型,并随时间调整这些类型。
How does this relate to SemVer?
这和SemVer有什么关系?
fixPATCHfeatMINORBREAKING CHANGEMAJORfixPATCHfeatMINORBREAKING CHANGEMAJORHow should I version my extensions to the Conventional Commits Specification, e.g. @jameswomack/conventional-commit-spec
?
@jameswomack/conventional-commit-spec我应该如何对约定式提交规范的扩展进行版本管理,例如@jameswomack/conventional-commit-spec
?
@jameswomack/conventional-commit-specWe recommend using SemVer to release your own extensions to this specification (and encourage you to make these extensions'!')
我们建议使用SemVer来发布你对该规范的自定义扩展(同时也鼓励你发布这些扩展!)
What do I do if I accidentally use the wrong commit type?
如果我不小心用错了提交类型怎么办?
When you used a type that's of the spec but not the correct type, e.g. fix
instead of feat
fixfeat当你使用了规范内的类型但类型不正确,例如把feat
写成了fix
featfixPrior to merging or releasing the mistake, we recommend using to edit the commit history. After release, the cleanup will be different according to what tools and processes you use.
git rebase -i在合并或发布错误之前,我们建议使用编辑提交历史。发布之后,清理方式将根据你使用的工具和流程而有所不同。
git rebase -iWhen you used a type not of the spec, e.g. feet
instead of feat
feetfeat当你使用了规范外的类型,例如把feat
写成了feet
featfeetIn a worst case scenario, it's not the end of the world if a commit lands that does not meet the Conventional Commits specification. It simply means that commit will be missed by tools that are based on the spec.
最坏的情况下,即使有不符合约定式提交规范的提交落地,也不是世界末日。这仅意味着该提交会被基于规范的工具忽略。
Do all my contributors need to use the Conventional Commits specification?
所有贡献者都需要使用约定式提交规范吗?
No'!' If you use a squash based workflow on Git lead maintainers can clean up the commit messages as they're merged—adding no workload to casual committers. A common workflow for this is to have your git system automatically squash commits from a pull request and present a form for the lead maintainer to enter the proper git commit message for the merge.
不需要!如果你在Git中使用基于压缩的工作流,核心维护者可以在合并时清理提交信息,不会给临时提交者增加工作量。常见的工作流是让你的Git系统自动压缩来自PR的提交,并提供表单让核心维护者为合并输入正确的Git提交信息。
How does Conventional Commits handle revert commits?
约定式提交如何处理回滚提交?
Reverting code can be complicated: are you reverting multiple commits? if you revert a feature, should the next release instead be a patch?
Conventional Commits does not make an explicit effort to define revert behavior. Instead we leave it to tooling authors to use the flexibility of types and footers to develop their logic for handling reverts.
One recommendation is to use the type, and a footer that references the commit SHAs that are being reverted:
revertrevert: let us never again speak of the noodle incident
Refs: 676104e, a215868回滚代码可能很复杂:你要回滚多个提交吗?如果你回滚了一个功能,下一个版本应该是补丁版本吗?
约定式提交没有明确定义回滚行为。相反,我们留给工具作者利用类型和页脚的灵活性来开发自己的回滚处理逻辑。
推荐使用类型,并在页脚中引用要回滚的提交SHA:
revertrevert: let us never again speak of the noodle incident
Refs: 676104e, a215868Attributing AI-Assisted Code Authorship
AI辅助代码的署名说明
When using AI tools to generate code, it can be beneficial to maintain transparency about authorship for accountability, code review, and auditing purposes. This can be done easily by using Git trailers that append structured metadata to the end of commit messages.
This can be done by appending one or more custom trailers in the commit message, such as:
Assistant-model: Claude CodeBecause most Git tooling expects trailers to be formatted as email addresses, you should use a different trailer key to avoid confusion and to distinguish authorship from assistance.
Co-authored-byTrailers can be added manually at the end of a commit message, or by using the command with the option:
git commit--trailergit commit --message "Implement feature" --trailer "Assistant-model: Claude Code"Trailers can be displayed using the pretty formats option to command. For example, for a formatted history showing the hash, author name, and assistant models used for each commit:
git loggit log --color --pretty=format:"%C(yellow)%h%C(reset) %C(blue)%an%C(reset) [%C(magenta)%(trailers:key=Assistant-model,valueonly=true,separator=%x2C)%C(reset)] %s%C(bold cyan)%d%C(reset)"2100e6c Author [Claude Code] Test commit 4 (HEAD -> work-item-8)
7120221 Author [Claude Code] Test commit 3
ea03d91 Author [] Test commit 2
f93fd8e Author [Claude Code] Test commit 1
dde0159 Claude Code [] Test work item (#7) (origin/main, origin/HEAD)使用AI工具生成代码时,保持作者身份的透明度对问责、代码审查和审计而言非常有益。你可以通过Git trailer轻松实现这一点,将结构化元数据附加到提交信息的末尾。
你可以在提交信息中附加一个或多个自定义trailer,例如:
Assistant-model: Claude Code由于大多数Git工具期望 trailer的格式为电子邮件地址,因此你应该使用不同的trailer键来避免混淆,区分作者身份和辅助贡献。
Co-authored-byTrailer可以手动添加到提交信息末尾,也可以在命令中使用选项添加:
git commit--trailergit commit --message "Implement feature" --trailer "Assistant-model: Claude Code"你可以使用命令的pretty formats选项查看trailer。例如,以下命令可以格式化展示提交历史,显示每个提交的哈希值、作者姓名和使用的AI助手模型:
git loggit log --color --pretty=format:"%C(yellow)%h%C(reset) %C(blue)%an%C(reset) [%C(magenta)%(trailers:key=Assistant-model,valueonly=true,separator=%x2C)%C(reset)] %s%C(bold cyan)%d%C(reset)"2100e6c Author [Claude Code] Test commit 4 (HEAD -> work-item-8)
7120221 Author [Claude Code] Test commit 3
ea03d91 Author [] Test commit 2
f93fd8e Author [Claude Code] Test commit 1
dde0159 Claude Code [] Test work item (#7) (origin/main, origin/HEAD)Important Notes
重要注意事项
- By default, pre-commit checks (defined in ) will run to ensure code quality
.pre-commit-config.yaml- IMPORTANT: DO NOT SKIP pre-commit checks
- ALWAYS attribute AI-Assisted Code Authorship
- If specific files are already staged, the command will only commit those files
- If no files are staged, it will automatically stage all modified and new files
- The commit message will be constructed based on the changes detected
- Before committing, the command will review the diff to identify if multiple commits would be more appropriate
- If suggesting multiple commits, it will help you stage and commit the changes separately
- Always reviews the commit diff to ensure the message matches the changes
- 默认情况下,将运行pre-commit检查(定义在中)以确保代码质量
.pre-commit-config.yaml- 重要提示:请勿跳过pre-commit检查
- 始终标注AI辅助代码的贡献来源
- 如果已经暂存了特定文件,命令将仅提交这些文件
- 如果没有暂存任何文件,命令将自动暂存所有已修改和新增的文件
- 提交信息将根据检测到的变更构建
- 提交前,命令将审查diff内容,判断拆分为多个提交是否更合适
- 如果建议拆分多个提交,命令将帮助你分别暂存和提交更改
- 始终检查提交diff,确保提交信息与变更内容匹配