4
层对象模型工作区、暂存区、本地仓库、远端。
Executive Summary
一、核心结论：Git 是 Codex 工作流的事实层
Codex 可以读、改、运行代码，但 Git 负责告诉你：它站在哪个分支、改了什么、哪些变化准备进入历史、如何回滚、如何交付给 review。
先查
任何任务从状态开始
让 Codex 先运行 git status、git branch、git diff，再决定是否动手。
再切
边界比速度重要
用分支和暂存区把“本次任务”和“已有改动”隔离，避免一锅粥式提交。
后证
提交是证据，不是仪式
好提交能回答：为什么改、改了什么、怎么验证、如何回滚。
教程使用方式
先读四层模型，再用命令地图建立“任务到命令”的对应关系，最后通过交互练习模拟真实 Codex 协作：选择命令、拆提交、处理分支同步、评估危险操作。
最重要的一句话
不要让 Codex 一上来就改代码。先让它用 Git 建立当前事实，然后你再限定任务边界。
适用场景
本地开发、网页生成、AI coding、PR review、恢复排障、Obsidian/文档项目版本管理。
CodexGitPRRecovery
Mental Model
二、先建立 Git 的四层心智模型
Git 不是“保存历史”的工具。它更像一套工程显微镜：当前文件怎么变、哪些变更准备进入历史、历史如何分叉、远端是否同步，都能被精确观察。
01 工作区
真实现场
Codex 修改代码、生成文档、运行格式化后，变化首先出现在这里。
演示文件：M docs/git-guide.md02 暂存区
提交候选
决定“哪些变化属于同一个语义单元”。这是拆提交的核心。
常用命令：git add -p03 本地仓库
可回滚历史
每个 commit 都应该可审阅、可解释、可定位、可回滚。
概念示例：commit message04 远端
协作坐标
PR、CI、review、发布和团队协作通常围绕远端分支展开。
远端引用示例：origin/mainGit status 的两列
短状态输出里，左列表示暂存区，右列表示工作区。一个文件可以同时 staged 和 unstaged，这也是提交前必须看 git diff --cached 的原因。
教学说明，不是当前仓库输出
# 教学说明：下面是格式解释，不是当前仓库输出
git status --short --branch
# 左列: index / staged
# 右列: working tree / unstaged
# MM docs/git-guide.md 表示已暂存过，又继续改了Git add 的真正含义
git add 不是简单地“添加文件”，而是“把此刻这份内容放进下一次提交候选”。对 Codex 来说，这意味着提交边界必须被明确管理。
常见误区
Codex 改了 6 个文件，不代表这 6 个文件都应该进同一个 commit。
Command Map
三、命令地图：按任务选工具，而不是背清单
把 Git 命令分成“观察、选择、记录、移动、协作、救援、诊断、并行、审计”后，Codex 的指令会清晰很多。
| 任务 | 核心命令 | 让 Codex 做什么 | 风险 |
|---|---|---|---|
| 看清现场 | git status --short --branchgit branch -vvgit diff --stat | 汇总分支、远端、未提交变更和风险。 | 跳过状态检查，把旧改动当成本次任务。 |
| 审阅变化 | git diffgit diff --cachedgit show --stat | 按文件解释行为变化、测试影响和破坏面。 | 只看文件名，不看实际 diff。 |
| 选择提交边界 | git add -pgit restore --stagedgit commit -m | 只暂存本次任务内容，生成 commit message。 | 把格式化、调试日志、功能改动混在一起。 |
| 创建任务分支 | git switch -cgit branch -vv | 解释从哪里切出，是否有 upstream。 | 在错误分支或陈旧 main 上开发。 |
| 同步远端 | git fetch --prunegit pull --ff-onlygit push -u | 比较 ahead/behind，再决定同步策略。 | 盲目 pull 产生不必要 merge commit。 |
| 恢复与回滚 | git restoregit revertgit refloggit stash | 先给恢复方案对比，危险命令等确认。 | 把 reset hard / clean / force push 当撤销键。 |
| 定位回归 | git bisectgit blamegit log -S | 先设计可重复测试，再二分定位。 | 凭感觉猜出错提交。 |
| 并行开发 | git worktree addgit worktree list | 在独立 worktree 中处理互不干扰的任务。 | 多个任务共享一个工作区，互相污染。 |
Codex Workflow
四、Codex 使用 Git 的标准作战循环
优秀的 Codex 指令不是“改一下”，而是给它一套可执行的边界：先读规则、再看 Git 状态、再改、再验证、最后解释提交范围。
1
读规则
AGENTS、README、测试说明。
2
看状态
git status、git diff --stat、git branch。
3
定边界
本次文件、用户改动、危险命令。
4
小步改
按行为单元实现。
5
验证
测试、lint、类型检查。
6
提交
审查 staged diff。
7
复盘
改动、验证、风险。
推荐节奏
小任务：一次状态检查 + 一次实现 + 一次验证。复杂任务：每个行为单元都生成 diff 摘要和验证证据。
Reusable Artifacts
五、可复用指令：直接交给 Codex 的 Git 模板
下面三段指令是“先保护现场、再推进任务”的基础工具箱。
只读巡检
适合打开陌生仓库或担心已有改动时。
prompt
请先只读检查当前仓库：
git status --short --branch
git branch -vv
git diff --stat
git log --oneline --decorate -5
然后汇总分支、未提交变更、远端状态和风险。不要改文件。实现并验证
适合任务边界已经明确后。
prompt
请在不改动无关文件的前提下完成任务。
先说明会改哪些文件；小步实现；运行相关验证；
如发现已有未预期变更，先报告；
最后输出 git diff 摘要、验证命令和剩余风险。提交前审查
适合准备 commit 或 PR 前。
prompt
请检查暂存区：
git status --short
git diff --cached
确认 staged 内容是否只包含本次任务。
如果边界不清，给出拆提交建议。
然后建议一个 commit message。Interactive Practice
六、交互练习：把抽象命令变成具体动作
练习只在页面内模拟，不会修改任何仓库。真正执行前仍应让 Codex 汇报当前 Git 状态。
练习 A：命令选择器
陌生仓库巡检
git status --short --branch
git branch -vv
git log --oneline --decorate -5
git diff --stat练习 B：提交雕刻台
勾选属于同一语义单元的文件，页面会生成建议命令。
建议
选择功能文件和对应测试，排除调试日志与无关文档。
generated commands
练习 C：merge / rebase / squash 怎么选
merge：保留分叉事实
适合需要保留完整分支上下文的协作场景。历史图会出现 merge commit，审计友好，但线性较弱。
merge 示例
# 示例分支名，请替换成你的真实分支
git fetch origin
git switch feature/demo-task
git merge origin/mainrebase：把本地提交移到新基线
适合尚未公开共享的个人 feature 分支，让历史更线性。已经推送并多人基于它工作时要谨慎。
rebase 示例
# 示例分支名，请替换成你的真实分支
git fetch origin
git switch feature/demo-task
git rebase origin/mainsquash：把过程压成一个结果
适合小功能或文档任务，PR 中过程提交较杂但最终行为单一。缺点是丢失中间推理轨迹。
squash 示例
# 示例分支名，请替换成你的真实分支
git merge --squash feature/demo-task
git diff --cached
git commit -m "docs: add Git Codex tutorial"Recovery
七、恢复排障：Git 的安全绳怎么用
恢复类命令要先判断“改动是否已经提交、是否已经推送、是否只是暂存、是否影响他人”。Codex 可以快速生成方案表，但涉及历史重写或删除文件时，必须先确认。
| 问题 | 优先命令 | 为什么 | Codex 应先问 |
|---|---|---|---|
| 工作区改错，尚未暂存 | git restore path | 只恢复指定路径。 | 要恢复哪个文件？是否有局部修改要保留？ |
| 已暂存但不想提交 | git restore --staged <file> | 撤出暂存区，不丢工作区修改。 | 撤出后是否继续编辑？ |
| 提交了但未推送 | git reset --soft HEAD~1 | 撤回提交但保留修改。 | 分支是否已共享？ |
| 提交已推送 | git revert SHA | 新增反向提交，不改写公开历史。 | 要 revert 哪个 SHA？ |
| 提交或分支找不到 | git reflog | 查看本地引用移动记录。 | 大概何时丢失？ |
风险雷达
风险等级：低。 可以继续，但仍应保留状态摘要。
Learning Path
八、30 天训练计划：从会用 Git 到会指挥 Codex
目标不是把所有命令背下来，而是在真实任务中形成“先观察、再选择、再记录、再复盘”的稳定习惯。勾选状态会保存在当前浏览器。
Quick Check
九、三个小测验：判断是否真的掌握
能回答这些问题，说明 Git 已经开始从“命令集合”变成“工程判断系统”。
Q1：提交前为什么看 git diff --cached？
Q2：已推送的错误提交，通常优先用什么撤销？
Q3：Codex 改代码前最应该先做什么？
Method & Sources
十、方法与参考资料
本教程采用“任务场景 -> Git 命令族 -> Codex 协作模板 -> 风险边界”的方法组织内容。Git 概念与命令口径以官方 Git 文档为主，GitHub 协作流程以 GitHub Docs 为辅助，Codex 相关描述以 OpenAI 官方文档为参考。
资料使用方式
官方资料用于确认概念、命令语义和工具边界；页面中的“Codex 协作方式”是基于这些资料和本地 Codex 工作流的综合建议。
生成信息
生成日期：2026-05-26。页面为本地单文件 HTML，无服务器、无部署、无外部 CSS/JS 依赖。
- Git Book: Recording Changes to the Repository - 工作区、暂存区、tracked/untracked、short status 与 git add 语义。
- Git Book: Branches in a Nutshell - 分支心智模型和提交图理解。
- Git Reference: git-restore - 工作区和暂存区恢复命令。
- Git Reference: git-reflog - 本地引用移动记录和找回误操作。
- Git Reference: git-bisect - 二分定位回归。
- Git Reference: git-worktree - 并行工作区。
- GitHub Docs: Pull requests - PR 协作语境。
- OpenAI Docs: Codex - Codex 处理代码任务的能力边界。