编写Git提交信息：记录修改目的与验证结果

如果提交列表中只留下“修改”“完成”“最终”，几周后再次遇到同样问题时，就很难知道该查找哪个修改。代码差异能够显示改了什么，却不会自动解释选择这种方式的理由，以及哪些范围尚未核实。提交信息是留给未来的自己和同事的一份简短说明，帮助理解修改。本文以一个小型缺陷修复为例，介绍如何组织标题、正文与验证记录。

1. 先确定一次提交要解释什么问题

要写好信息，修改集合的大小必须便于解释。例如，同时加入搜索结果中处理空字符串的代码和登录界面的颜色修改，“修复搜索结果错误”这一标题就无法涵盖全部修改。如果两项工作的目的与回退理由相互独立，拆成不同提交更便于查找记录。不必仅因涉及文件较多而一定拆分。如果代码、测试和说明文档都为了解决同一问题而修改，它们可以属于一个目的。

工作结束后，不要急着勉强拟定标题，可以分别用一句话写出“什么情况下出现问题”和“本次修改如何处理这种情况”。如果这两句话无法衔接，工作范围可能仍不明确。还要检查是否混入临时调试输出或无关的格式修改。应先整理实际的修改集合，而不是靠提交信息掩盖混杂的修改。

2. 标题用于识别修改，正文用于解释理由

Git官方文档介绍了先写简短标题、空一行，再写详细说明的结构。标题约不超过50个字符，是为了可读性的建议，并非适用于所有项目的存储限制。与其机械地使韩文标题符合英文标准，不如先核实团队规则，确保在列表中能读出核心意思。最好仅阅读标题就能了解修改对象与动作。

例如，与其写“修复缺陷”，不如写“搜索词为空白时跳过结果请求”，这样条件与行为都清楚。如果没有真实依据，应避免“显著提升搜索性能”等需要测量支持的表述。“解决全部错误”也可能超出验证范围。标题应写本次提交已经完成的事情，未来计划与尚未解决的问题则另外留在正文中。

项目	应记录的内容	说明用示例
标题	修改对象与动作	搜索词为空白时跳过结果请求
问题	修改前的具体条件	仅输入空白也会创建搜索请求
理由	选择这种方式的原因	在请求前进行规范化，减少不必要的调用
验证	实际检查的项目与结果	检查空输入、空白输入与普通输入的情况
剩余范围	尚未核实或需另行处理的部分	未核实真实服务器响应与移动端界面

3. 不要记录实际上未进行的验证结果

下面是一条用于展示写法的假设提交信息。其中所列的行为检查并非真实项目测试结果。使用时，请替换为你在实际工作中执行的项目。尤其当AI生成草稿时，应检查是否包含未执行的测试命令或“所有测试通过”等文字。应分别记录编写者预期的行为与实际执行所确认的行为。

검색어가 공백일 때 결과 요청 생략

문제: 공백만 입력해도 검색 요청이 생성된다.
변경: 입력을 정리한 뒤 길이가 0이면 요청을 생략한다.
이유: 결과 처리 단계보다 요청 생성 단계에서 조건을 판단한다.

검증: 이 줄에는 실제 수행한 확인 항목과 결과를 적는다.
미확인: 실제 서버 연동과 모바일 화면은 별도 확인이 필요하다.

验证记录最好不要只写“检查完成”，而应将条件与结果配对。例如，分别记录普通搜索词是否保持原有调用、空白时是否跳过调用、错误情形是否仍显示原有错误信息，以便日后查找回归问题。记录失败测试时，应将失败原因的推测明确标为推测，不要改写成已经通过。

即使尚未执行，也能写出有用的信息。可以写“验证：已检查代码差异，未进行运行测试”，说明目前的检查程度，并另外列出待执行项目。新增测试代码与执行该测试是两件事：前者属于修改内容，后者属于验证记录。这一区分能直接帮助同事判断接下来应做什么。

4. 保存前对照暂存范围与说明

基本的提交会记录暂存区中准备好的内容。如果认为只要在编辑器中保存文件，其全部最新修改就都会进入本次提交，信息便可能与实际代码不符。如果只暂存了部分修改，同一文件中也可能有些行被包含，其他行仍留在工作区。请在所用Git界面中阅读本次提交将包含的差异，确认信息所说明的修改位于该范围内。

可以通过三次对照简化信息审查。第一，核实标题中的行为能否在实际差异中看出。第二，核实正文中的理由是否与代码条件或注释矛盾。第三，如果修改了公开接口或文档，确认说明是否遗漏。此时还应从示例或日志中删除不应留在记录里的密码、令牌、真实客户资料等内容。

不过，不必为了把提交信息写得完美而额外修改无关代码。发现的其他问题可以留给下一次工作，先明确当前目的。如果“修改搜索请求条件”中包含为了说明该条件而调整的文档，可以一起说明；但改写整个文档的文风属于另一目的。考虑回退时这些修改是否必须一起回退，有助于判断如何分组。

5. 用编辑器或文件编写较长的信息

简短信息可以通过git commit -m "搜索词为空白时跳过结果请求"传入。如果需要多个段落，使用默认编辑器，或先将信息写入UTF-8文本文件，再通过git commit -F commit-message.txt读取，会更方便。这些命令会在当前仓库实际创建提交，因此执行本文示例前，应先检查已准备好的修改范围。

信息文件第一行写标题，下一行留空，然后写说明。请核实是否确实希望将文件中的文字原样记录。如果编辑器模板中的提示语也留在文件里，就可能把不希望记录的说明写入历史。若将长信息转成Shell中的单行字符串时丢失了换行或引号，文件方式会更便于阅读和审查。如果团队规定了模板，应优先使用。

如果希望每次采用相同项目，可以先使用“问题、修改、验证、未核实”四行框架，不必强制每个项目都写成长篇。简单的错字修正可能只需一行标题，而改变外部API行为或数据格式的工作，则可能需要说明适用条件与兼容性。记录长度应与修改风险和解释所需信息相适应。

6. 检查列表和详情中的可读性

git log -5 --oneline是读取命令，以简短标识符与标题为中心显示最近的提交。如果界面中连续出现“修改”“新增”“完成”，记录就很难检索。即使正文很长，列表中往往也只显示标题，因此标题应包含对象与动作。需要详细说明时，可以在普通的git log -1输出中阅读最近一次提交的信息。

在列表中可以问三个问题：查找搜索输入问题的人能否选中这个标题？能否与UI颜色修改区分？能否理解本次修改是新增、修正还是删除？如果为了理解标题而打开正文的次数减少，记录就更有用。提交哈希能识别修改，却不能解释问题含义，因此还需要供人阅读的标题。

7. 按项目规则使用前缀与问题编号

fix:、feat:、docs:等前缀可能是团队或工具制定的规则，并非Git对所有仓库强制的语法。如果项目使用自动发布工具读取信息，应先核实该工具的规则。个人仓库可能只需选择几个一致使用的分类，不必增加很多前缀。即使前缀正确，若标题是“其他修改”，仍难以查找内容。

添加问题编号时，也不要只留下编号，应以句子说明核心问题。这样即使日后无法访问问题追踪系统，或单独保存仓库，也能理解修改。将实际问题的详细记录放在问题追踪条目中，将本次提交的选择与验证范围放在信息中，职责便更清楚。自动关闭问题的语法可能因服务而异，不应惯性地加入未核实的关键词。

8. 可直接使用的最终检查表

• 标题是否包含修改对象与动作？
• 标题后是否空一行以分隔正文？
• 是否具体记录了修改前出现问题的条件？
• 是否解释了仅凭代码差异难以理解的选择理由？
• 验证记录是否与实际执行的项目一致？
• 是否避免把未执行的范围表述为通过？
• 已准备的修改与信息说明的范围是否相同？
• 是否符合团队规则与问题关联方式？

好的记录依靠可检索的条件与可信的验证范围，而非华丽文风。可以设想未来分析错误的人会阅读今天的信息。如果保留了“为什么添加这个条件”和“检查到了什么范围”，代码变化就有了判断依据。实践中，可以先从简短标题和两三句正文开始，仅在需要解释的修改中扩展内容。

官方来源与撰写依据

• Git官方文档：git commit
• Git官方文档：git log

资料核查日期：2026-10-10。本说明由AI根据实际打开查阅的官方资料撰写。另行标注的计算、代码与检查案例仅用于说明，并非对用户环境直接进行测试或实际测量所得的结果。发布时会再次核实功能与资料是否发生变化。

创建提交记录的步骤

1. 整理问题条件与修改目的

→

2. 检查提交将包含的差异

→

3. 编写标题 → 空行 → 理由

→

4. 记录实际验证与未核实范围

→

5. 保存后检查列表与详细信息

这是解释正文内容的示意图，并非实际产品界面或测量资料。