先记住这一句

核心录音给出的直觉是：Git 是“平行世界的时光机”。这个类比很有力量，因为它让分支实验、选择路线和回到历史节点变得可感知；但它还不够精确。完整模型需要再补三块：

1. 快照不是录像：Git 不会记录每一次编辑，只记录你明确选择并提交的状态。
2. 分支不是文件夹副本：branch 主要是一个指向 commit 的可移动引用；worktree 才是额外的物理工作目录。
3. 合并不是自动判对：Git 能处理文本与图结构，却不能替你判断产品语义、业务意图和结果是否正确。

1. 学习目标与资料边界

你读完后应能回答什么

• Git 到底保存什么？为什么说 commit 是快照，又为什么 diff 仍然重要？
• working tree、index、HEAD、branch、remote 分别是什么状态或指针？
• merge、rebase、squash、cherry-pick 都在“整合”，它们改变的因果结构有什么不同？
• restore、reset、revert、reflog 都像“撤销”，什么时候安全，什么时候会伤害共享历史？
• branch 与 worktree 到底是什么关系？为什么多 Agent 并行时仅有分支还不够？
• fetch、pull、push、PR 为什么不是四个同义的“同步”？
• 冲突为什么是决策界面，而不是 Git 出故障？
• 如何让 Git 历史成为未来自己、协作者和 AI 都读得懂的知识库？

资料权重

• 一手事实：Git 官方文档与 Pro Git 用于定义对象、引用、命令行为与边界。[G1][G2]
• 建议与推断：关于 AI Agent 的提交粒度、并发隔离、语义合并风险，是基于 Git 机制与本地工程材料的实践归纳，不是 Git 官方强制规范。[N3][L5]

2. 三组主类比：先搭桥，再检查桥会在哪里断

A. 档案馆 + 时光机

最有用的直觉：commit 不是“保存一下”，而是“让项目历史多出一个可解释、可定位、可审查的节点”。

类比边界：真实时光机暗示“过去被改变后现在自动跟着改变”；Git 的 commit 通常不可变。所谓改写历史，实际上是生成新 commit 并移动引用，旧对象在一段时间内可能仍可由 reflog 找到。[G2][G9]

B. 平行世界 + 独立房间

核心录音的小说案例非常适合这个类比：先提交“16 年前发生凶案、16 年后发现尸体”的共同世界，再用多个 branch 尝试不同主角，最后选择、组合或放弃路线。[N1]

类比边界：删除 branch 只是删掉路标，不保证相关 commit 立刻从对象库消失；同样，保留 branch 也不等于成果已经验证正确。

C. 物流网络 + 可移动路标

这组类比最适合解释 remote、fetch、push 和引用。

类比边界：网络同步不是把目录做字节级镜像；Git 交换的是对象和引用，并受可达性、权限、fast-forward 与服务端规则约束。[G7][G8]

3. Git 的物理世界：对象、图、引用、现场

四层总图

3.1 Blob：只关心内容，不关心文件名

• 是什么：文件内容对象；身份来自内容哈希。
• 关键关系：tree 把文件名、模式与 blob/tree 对象连接起来。
• 价值：相同内容可以被复用；内容变化意味着对象身份变化。
• 陷阱：不要把“内容寻址”理解成绝对安全证明。Git 已推进 SHA-256 相关能力，但仓库格式、兼容性和签名验证仍是更完整的话题。[G2]

3.2 Tree：目录快照的结构

• 是什么：记录某一目录下名称、权限模式与对象 ID 的映射。
• 作用：递归构成完整项目树，使 commit 能指向一次完整根目录快照。
• 类比：档案袋里的目录索引；不是文件内容本身。

3.3 Commit：快照 + 元数据 + 父关系

一个 commit 至少表达三件事：

1. 项目当时的根 tree；
2. 作者、提交者、时间和 message；
3. 零个、一个或多个父 commit。

首个 commit 没有父；普通 commit 通常一个父；merge commit 通常两个或更多父。commit ID 因内容与父关系而定，所以 rebase 即便得到相同文件结果，也会生成身份不同的新 commit。[G2][G5]

3.4 DAG：历史不是时间线，而是因果图

3.5 Ref：给 commit 起一个会移动的名字

• branch：通常指向某个 commit；在该分支上新建 commit 时向前移动。
• tag：给某个对象起稳定名字；annotated tag 还能携带说明、tagger 和签名。
• remote-tracking ref：本地记录“上次 fetch 后所见远端分支位置”，例如 origin/main；不是远端实时状态。
• HEAD：表示当前检出位置，通常符号指向 branch；detached HEAD 时直接指向 commit。

3.6 Reflog：引用移动的本地黑匣子

4. 三棵树模型：绝大多数操作都在移动“内容”或“指针”

理解三棵树，才能区分三种 diff：

最关键的因果：git add 不是“把文件标记一下”，而是把当下内容写入 index。之后继续编辑同一文件，working tree 与 index 会再次不同。[G1]

文件状态

• untracked：工作区存在，但不在当前历史跟踪集合中。
• tracked / unmodified：与当前基线一致。
• modified / unstaged：工作区与 index 不同。
• staged：index 与 HEAD 不同，已进入下一快照候选。
• ignored：匹配 ignore 规则而默认不进入普通未跟踪提示；已被跟踪的文件不会因新增 .gitignore 自动停止跟踪。[G11]

5. 核心概念地图：名词、动作、目的、边界

5.1 建仓与获取

5.2 观察与比较

5.3 形成提交

原子提交不是“越小越好”。它的尺度应满足：只有一个意图、节点可构建/验证、撤销时不会带走无关变化、审查者能形成完整判断。[N3]

5.4 指针与路线

5.5 临时搁置与多现场

5.6 远程交换

6. 分叉与整合：merge、rebase、squash、cherry-pick

一张决策表

Merge：保留两条历史的会面

Git 通常先找共同祖先（merge base），再比较两条路线相对祖先的变化。没有重叠歧义时可自动组合；有歧义时把冲突交给人。真正的 merge commit 同时指向两个父节点，因此保留“这两条历史在这里会面”的事实。[G4]

准确类比：两位编辑分别在同一旧稿上修订，最终拿旧稿、甲版、乙版三份材料对照整合。

边界：没有冲突只说明 Git 在文本/路径层面找到可组合结果，不代表接口语义、数据库迁移顺序、权限逻辑或 UI 行为正确。[N3]

Rebase：换一个祖先重新演算

Rebase 会找出当前路线独有的提交，把这些变化在新基线之上依次重放，生成新 commit。文件最终内容可能与 merge 相似，但历史身份和叙事不同。[G5]

建议：

• 未共享个人 feature branch：可以用来整理和降低合并噪声。
• 已被他人基于其开发的 branch：除非团队明确协议，否则不要随意 rebase + force push。
• 必须强制更新时优先考虑 --force-with-lease 的保护语义，但它仍是高风险动作，先确认远端没有未知新提交。

Squash：把过程压成一个交付节点

Squash 适合把大量 WIP/修正提交整理为一个主线语义单元。它改善主线可读性，但会丢掉分支内部可独立定位/回滚的细节。不要把“整洁”绝对化：调试与审计同样需要有意义的中间节点。

Cherry-pick：摘取变化，不搬整条路线

适合把已知修复搬到 release branch，或从实验中选取一个独立成果。它创建新 commit，不能把两个相似 ID 当成同一个历史节点。频繁 cherry-pick 往往暗示分支策略或发布线管理需要重看。

7. 撤销与恢复：先判断“要撤销哪一层”

Restore、Reset、Revert 的对象不同

Reset 三种常见模式

• soft：移动 branch，保留 index 和 working tree；适合重新组合最近本地提交。
• mixed（常见默认）：移动 branch 并重置 index，保留 working tree；适合把提交拆回待选择修改。

Reflog 是恢复入口，不是永生保险

常见恢复思路：先停手 → 看 status → 看 reflog → 找到误操作前的 commit → 创建新 branch 指向它 → 再比较。不要一慌就继续 reset，连续移动指针只会增加认知负担。[G9]

Clean、Stash、未跟踪文件

• clean 面向未跟踪文件，风险不在 commit 历史保护范围内；先 dry-run。
• stash 默认行为与未跟踪/忽略文件处理取决于选项；不要假设“所有东西都被藏好了”。
• 长期重要 WIP 应进入清晰 branch/commit，不要让 stash 列表变成无标题仓库。

8. Branch 与 Worktree：路线与房间

为什么只有 branch 仍可能不够

在单一工作目录里切 branch，会同时切换目录内容；未提交修改、构建产物、依赖缓存、正在运行的服务和终端上下文都可能阻碍或污染切换。多个 worktree 让不同 branch 同时出现在不同目录，各自拥有工作区和 index，同时共享仓库对象库。[G3]

Worktree 真正隔离什么

• 独立工作目录与可见文件状态；
• 与该 worktree 关联的 HEAD 和 index；
• 每个任务自己的终端、开发服务器和临时上下文。

Worktree 不隔离什么

• 共享的 Git 对象数据库和大部分仓库配置；
• 外部共享资源，例如同一数据库、端口、云环境或系统级依赖；
• 合并时的文本冲突与跨分支语义冲突；
• 人对任务边界、依赖和验收标准的责任。

多 Agent 并行的最小治理模型

建议：每个并发任务必须同时拥有五个边界：责任文件、branch、worktree、验证命令、完成定义。缺一项，就可能只是“并行活动”，不是“可整合的并行工作”。[N3][L6]

9. 远程协作：Git、GitHub 与发布层分开理解

Git ≠ GitHub

• Git：对象、引用、历史、比较、传输协议；本地可完整运行。
• GitHub/GitLab 等平台：仓库托管、身份权限、Pull Request、Issue、Discussion、Checks、Actions、保护规则、Release 与社区关系。[GH1]
• CI/CD：监听提交或 PR，运行构建、测试、扫描和部署；它输出证据，但也会受测试覆盖、环境和权限配置限制。

Fetch、Pull、Push 的精确区别

Fetch：先把信息拿回来

获取远端对象并更新本地 remote-tracking refs，不自动把它整合进当前 branch。适合“先看看大家发生了什么，再决定怎么接”。[G7]

Pull：获取 + 整合

通常等价于先 fetch，再按配置或参数 merge/rebase。它会改变当前历史，因此在脏工作区或不清楚团队策略时，盲目 pull 容易把两个问题混在一起。[G8]

Push：发布历史并申请移动远端 ref

它不是保存动作，而是协作动作。non-fast-forward 拒绝意味着远端 ref 已含你本地没有纳入的历史，系统在阻止静默覆盖。[G8]

PR、Issue、Fork、Release

10. 冲突：Git 把无法替你决定的歧义显性化

冲突的三层

1. 文本冲突：同一区域存在无法自动组合的修改，Git 标出冲突块。
2. 结构冲突：重命名、删除/修改、目录变化等让路径关系不明确。
3. 语义冲突：文本可自动合并，但两边对接口、数据、权限或业务规则的理解互相矛盾。第三类最危险，因为 Git 可能显示“合并成功”。[N3]

安全处理顺序

1. 停止继续叠加无关修改；
2. 看 status，确认正在进行 merge、rebase 还是 cherry-pick；
3. 找 merge base，理解两边各自意图，而不只是删除冲突标记；
4. 在目标文件里形成第三个正确版本；
5. 搜索冲突标记是否清理干净；
6. 运行相关测试、类型检查、构建与关键路径；
7. 阅读最终 diff，再完成整合；
8. 如果不确定，使用对应 abort 返回操作前状态，而不是强行提交。

Rerere 与复用冲突解决

Git 的 rerere 能记录并复用曾经的冲突解决方式，适合重复 rebase/merge 的团队；但自动复用的结果仍需验证，尤其当语义背景已改变。

11. 历史诊断：把 Git 从“保存工具”升级为调查系统

Log：先看图，再看故事

• 分支图回答“在哪里分叉与汇合”；
• commit message 回答“为什么产生节点”；
• diff 回答“具体改变了什么”；
• PR/Issue/ADR 回答“当时讨论、选择和限制是什么”。

任何一层缺失，历史解释力都会下降。只看 log --oneline 很快，但可能把复杂因果压扁成标题列表。

Bisect：对提交图做二分实验

给定一个已知 good 节点和一个已知 bad 节点，Git 选择中间候选让你测试，从而不断缩小引入回归的范围。它的力量依赖两个前提：

• 每个 commit 在该节点上可构建/测试；
• 测试能稳定判定 good/bad。

巨型 commit 即使被 bisect 命中，内部仍然难定位，这正是 atomic commit 的工程价值。[N3]

Blame：找上下文，不找罪人

行级最后修改者只是调查入口；真正原因可能在更早重构、自动格式化、代码生成或需求变化里。正确用法是从行追到 commit，再追到 diff、message、PR 和测试。

12. 配置、忽略、钩子与仓库边界

Config 的作用域

常见层级包括 system、global、local/worktree 等；后者覆盖前者。重要的不是背路径，而是每次知道“这个配置影响谁、在哪里定义、能否被仓库携带”。

.gitignore 不是安全工具

• 用于声明不应被普通跟踪流程纳入的生成物、缓存或本地配置模式；
• 不会删除已经进入历史的文件；
• 不会扫描秘密，也不保证同名文件从未被其他规则包含；
• 团队共享规则放 .gitignore，个人本地排除可用仓库 exclude 或全局 excludesfile，按场景选择。[G11]

Hooks：本地自动化触点

hooks 能在 commit、merge、push 等事件前后运行检查或自动化。客户端 hook 默认不会随 clone 自动启用，因此关键治理不能只依赖个人本地 hook；服务端保护、CI 和可重复脚本更可靠。[G10]

Submodule、Subtree、Monorepo

• submodule：父仓库记录另一个仓库的特定 commit；能精确钉住依赖，但初始化、更新和协作认知成本较高。[G12]
• subtree：把外部项目内容合入某个目录并保留同步策略；使用体验更像单仓库，但同步历史管理也有成本。
• monorepo：多个项目共享一个仓库与历史；一致性强，但规模、权限、构建和 ownership 需要额外工具。

Git LFS 与大文件

Git 擅长文本和可差异审查的内容；视频、模型权重、大型设计源文件会放大 clone、存储和历史成本。LFS 用小指针替代普通 Git 对象中的大文件内容，但仍需服务端、配额、备份与迁移策略。

13. 安全与可信历史

Git 是证据链的一部分，不是全部

• 内容哈希帮助发现对象变化，但不能自动证明作者身份或业务正确性；
• commit/tag 签名增强来源验证，但密钥管理、信任链和平台显示策略同样重要；
• 分支保护与 required checks 能限制流程，但配置错误或测试不足仍会放行缺陷；
• Git 历史不是秘密保险箱：一旦密钥进入 commit，即使后续删除文件，旧对象仍可能存在于历史、克隆、缓存和镜像。

敏感信息进入历史后的原则

1. 先轮换/吊销凭据，把泄露视为已经发生；
2. 再评估历史清理范围、所有克隆与远端镜像；
3. 使用专门工具重写历史并协调所有协作者；
4. 增加 secret scanning、pre-commit 检查和服务端保护；
5. 不要只做一次“删除文件”的新 commit 就宣布处理完毕。

备份边界

Git 能通过多个 clone 提供分布式冗余，但它不天然覆盖未提交工作、外部数据库、LFS 对象、Issue/PR 讨论、CI secrets、Release 附件或托管平台元数据。重要项目仍需独立备份和恢复演练。

14. 最佳实践：个人、团队、AI Agent 三种工作流

14.1 个人创作者 / 独立开发者

1. 一个真实目标，一条实验路线：只有存在真实不确定性时分支；分支名写任务或假设。
2. 提交前完成观察三件套：status → diff → 测试/预览。
3. 按意图提交：HTML、文档、Skill 和代码都遵守一个 commit 一个完整意图。
4. 公开前做隐私检查：绝对路径、真实 IP、邮箱、密钥、内部状态与用户数据。
5. 设置远端但不把远端当唯一备份：验证能从干净环境恢复。

14.2 小团队

1. main 受保护，默认通过 PR 合并；
2. required checks 与实际风险匹配：测试、类型、构建、安全扫描；
3. code owners 或模块 owner 负责公共接口；
4. PR 说明目标、范围、风险、验证、回滚和截图；
5. 统一 merge/rebase/squash 策略，不让每个人临时发明历史风格；
6. release tag、制品和部署环境都能追溯到 commit；
7. 定期验证恢复、权限和分支保护，而不是只配置一次。

14.3 AI Agent 工作流

• 隔离：每个 Agent 独立责任范围、branch 和 worktree；避免共享脏目录。
• 透明：提交写清任务、原因、验证和限制；PR 保存人机交接信息。
• 可验证：不把 Agent 的“完成”当证据，保存测试输出、构建结果和可观察产物。
• 最小权限：Agent 不应默认拥有 force push、生产发布、秘密访问或全仓删除权。
• 合并后复验：分支各自通过不代表组合后正确；在集成节点重新跑测试。

15. 提交与 PR：让历史成为未来 AI 可读的知识库

Commit message 模板

<type>: <一句话说明语义变化>

为什么：原问题、约束或决策背景
怎么验证：测试、构建、截图或最小探针
限制：未覆盖范围、兼容性或后续工作

不要机械追求 Conventional Commits；它只是可选协议。真正目标是让节点的意图、范围和验证可恢复。

PR 最小信息

• 目标：解决什么问题，成功是什么；
• 范围：改了什么，明确没改什么；
• 决策：为什么选这个方案，替代方案为何没选；
• 证据：测试、构建、截图、性能或兼容性结果；
• 风险：数据、权限、迁移、回滚与观察指标；
• 审查提示：最需要人判断的 1–3 个位置。

16. 常见误区与纠偏

17. 场景手册：遇到什么情况，先想到什么

想尝试两个 UI 方向

建议：从同一基线开两个 branch；需要同时运行就用两个 worktree。分别定义截图、交互和验收标准，最后比较证据，而不是让两个 Agent 在同一目录互改。

AI 一次改了几十个文件

先做：status / diff --stat / 按目录看 diff。确认是否混入格式化、锁文件、生成物、调试代码和不相关重构。必要时重新拆任务，不要用一个巨型 commit 把混乱合法化。[N3]

本地提交很乱但还没推送

建议：先建临时恢复 branch；再用交互式 rebase、reset mixed 或分段暂存整理成语义 commits；每个节点重新验证。

已推送的提交要撤销

默认：新增 revert，使团队看到错误与修复；除非团队明确协调历史重写，否则不要用 force push 擦除共享事实。[G7]

Pull 产生冲突

先拆问题：先 fetch，观察本地 branch 与 origin/... 的分歧；再选择 merge 或 rebase。不要让“下载”和“整合”同时发生后才开始理解。

误删 branch / 误 reset

先停手：看 reflog，找到原尖端，创建恢复 branch。不要继续做清理和 GC。[G9]

想同步 Obsidian / 文档库

文本非常适合 Git；图片、附件和多设备自动同步需要额外策略。先 pull/fetch 再编辑、明确冲突处理，重要改动手动 commit/push。整体回退优先考虑新增 revert；文件级恢复可用 restore，但执行前确认未提交内容。[N5]

18. 一份够用的“观察优先”命令地图

这不是让你背命令。你只需在 AI 执行前能回答：

1. 它会改变 working tree、index、branch、对象库还是 remote？
2. 它会覆盖未提交内容吗？
3. 它会改写已经共享的 commit ID 吗？
4. 完成后用什么证据验收？

19. 四周学习路线：从理解到真正会用

Week 1｜看懂状态

• 在一个真实小项目中练 status、三种 diff、show、log --graph；
• 每天做 2–3 次有意图的 commit；
• 能画出 working tree → index → commit 的流转图。

Week 2｜制造并比较路线

• 为一个真实设计选择开两个 branch；
• 用 merge 合流一次，用 rebase 在未共享 branch 上重放一次；
• 解释二者文件结果与历史结构的区别；
• 故意制造一个小冲突并安全 abort / 解决。

Week 3｜恢复与调查

• 在练习仓库中体验 restore、revert、reset 三层差异；
• 用 reflog 找回一个故意移动掉的 branch；
• 用 bisect + 自动测试定位一个故意引入的 bug；
• 写下哪些内容 Git 无法替你恢复。

Week 4｜Agent 与协作

• 为两个独立任务建立两个 worktree；
• 每个 Agent 只拥有明确责任范围；
• 用 PR 模板记录目标、证据、风险与回滚；
• 合并后重新跑组合测试；
• 从干净目录 clone 并验证项目可恢复。

20. Teach-back：完成学习闭环前仍缺的一步

请在下一轮用自己的话回答四件事：

1. Git 保存的核心对象和历史关系是什么？
2. working tree、index、commit、branch、HEAD 的关系是什么？
3. branch 与 worktree 为什么一个是“路线”、一个是“房间”？
4. 为什么共享历史出错时通常优先 revert，而不是 reset/rebase + force push？

届时使用 canonical prompt 8 做事实准确性、因果完整性、边界意识和遗漏概念校验。

自我拷问结论

• 边界：本报告覆盖 Git 的核心心智模型与高频工程概念，不替代特定仓库的团队协议、合规要求、托管平台配置或逐命令手册。

资料索引

Git / GitHub 一手资料

• [G1] Pro Git：Git Basics
• [G2] Git Glossary
• [G3] git-worktree Documentation
• [G4] git-merge Documentation
• [G5] git-rebase Documentation
• [G6] git-reset Documentation
• [G7] git-revert Documentation
• [G8] git-fetch / git-pull / git-push
• [G9] git-reflog Documentation
• [G10] githooks Documentation
• [G11] gitignore Documentation
• [G12] git-submodule Documentation
• [GH1] GitHub Docs：About GitHub and Git

• [L1] 03-Git版本控制-来源-Claude-Code.html
• [L2] 03-Git版本控制-来源-Codex-CLI.html
• [L3] 03-Git版本控制-来源-Gemini-3.1-Pro.html
• [L4] 03-Git版本控制-来源-Gemini-3.6-Flash.html
• [L5] 20260814-Git-TDD-AI系统化试错指南.html
• [L6] Parallel Work Needs Separate Rooms / x-article-copy.html
• [L7] GitHub学习作战地图.html