6.3 本地提交流程：从 status 到 commit

面向经管学生、研究者与从业者的 AI 智能体设计教材

6.3 配图

这一节只做一件事：把最基础、最常用、本章最重要的本地提交流程走一遍。读者如果先把这条链练熟，再接入 AI 协作，会稳很多。

最小提交路径

假设你刚让智能体改完一轮章节内容，现在准备把这一轮落成一个本地提交：

git status
git diff
git add chapters/chapter-6/section-6-1.qmd
git add chapters/chapter-6/section-6-2.qmd
git diff --cached
git commit -m "docs: rewrite git chapter for hands-on workflow"

这几步的顺序不要乱：

1. git status 看改动范围。
2. git diff 检查正文到底改了什么。
3. git add 只挑本次要提交的文件。
4. git diff --cached 再确认一次暂存区内容。
5. git commit 形成提交点。

如果改动范围很大，不要直接 git add .。这会把顺手修改、临时文件和无关调整一起打包进去。

按块暂存

当一个文件里同时包含“该提交的修改”和“还没想好是否要保留的修改”时，可以用：

git add -p

-p 表示按块暂存。Git 会把 diff 分成若干块，逐块询问是否加入暂存区。对 AI 协作来说，这个命令很有价值，因为模型经常在同一文件里同时做核心改动和顺手修辞。

提交信息的写法

提交信息不需要花哨，但要让人看得出这次提交的目标。比较稳的写法是：

类型: 这次提交解决了什么

例如：

docs: reorder part-two chapters and rewrite git workflow
docs: tighten preface wording for new chapter order
chore: add quarto selection mapping for chapter 6

一条提交只说一件事，后续才容易审，也容易回退。

小步提交的好处

每次提交只包含一个明确目的的改动。提交越小，回退越精准，审阅越容易，出问题时排查范围也越窄。与 AI 协作时尤其如此——模型单轮改动范围往往较大，拆成多个小提交能有效控制风险。

提交后确认

本地提交完成后，不要立刻离开。至少再做两步：

git log --oneline -n 5
git show --stat --oneline HEAD

第一条确认提交已经进入历史。第二条确认这一版到底触及了哪些文件、规模是否合理。

本地回退

回退不是失败，而是工作流的一部分。初学阶段最常用的本地回退主要有三类：

# 丢弃工作区中尚未暂存的修改
git restore chapters/chapter-6/section-6-3.qmd

# 取消暂存，但保留文件修改
git restore --staged chapters/chapter-6/section-6-3.qmd

# 回看某个历史提交
git show HEAD~1

本章不鼓励读者一开始就大量使用高风险回退命令。先把“恢复工作区”和“取消暂存”练熟，已经足够覆盖大多数基础场景。

本节最小结论

真正重要的不是会不会背命令，而是能不能形成固定顺序：status -> diff -> add -> diff --cached -> commit -> log。