Git 与 Codex 交互式学习手册缩略图
G Git × Codex 手册
把 Git 变成 Codex 的仪表盘、安全绳和审计记录 🚀

Git × Codex交互式学习手册

本手册把 Git 拆成可理解、可练习、可让 Codex 执行与复盘的工作流：先看清状态，再限定边界，最后用提交、分支、PR 和恢复工具把开发过程变得可控。

开始交互练习 查看 Codex 协作框架
4层对象模型：工作区、暂存区、本地仓库、远端
9类高频命令：从 status 到 worktree
30天训练路径：从会用到会指挥 Codex
codex@repo: git status --short --branch
A:init B:main C:feature D:merge E:tested
$ git status --short --branch
## feature/git-codex...origin/feature/git-codex
M tutorial.html
?? assets/diagram.svg
✓Codex 的第一步不是改代码，而是建立“当前事实”。
✓Git 的第一原则不是提交，而是控制每次提交的语义边界。

一、先建立 Git 的四层心智模型

Git 不只是“保存历史”的工具。它更像一套工程显微镜：当前文件怎么变、哪些变更准备进入历史、历史如何分叉、远端是否同步，都能被精确观察。

工作区 暂存区 本地仓库 远端 可回滚历史
1. 工作区

文件的真实现场。Codex 修改代码、生成文档、运行格式化后，变化先出现在这里。

M src/app.ts
2. 暂存区

下一次提交的候选内容。这里决定“哪些变化属于同一个语义单元”。

staged hunk
3. 本地仓库

已形成快照的历史。提交要小、清楚、可审阅、可回滚。

a1b2c3 fix: ...
4. 远端

团队协作的公共坐标。PR、CI、review、发布通常围绕远端分支展开。

origin/main

二、Git 命令不是背清单，而是按任务选择工具

把命令按“观察、选择、记录、移动、协作、救援、诊断”分类后，Codex 才能被明确地指挥：该只读就只读，该分阶段提交就分阶段提交，该停下来确认就停下来确认。

建议先把左列变成肌肉记忆，再把右列交给 Codex 做高质量复盘。人负责判断边界，Codex 负责快速执行和解释。

任务类型 核心命令 Codex 协作方式 常见风险
看清现场 git status --short --branch
git diff --stat
git log --oneline --decorate -5		 让 Codex 先给“分支、改动、远端、风险”摘要表。 跳过状态检查，误把历史变更当成本次任务。
审阅变化 git diff
git diff --cached
git show --stat		 让 Codex 按文件解释 diff，并标出行为变化和测试影响。 只看文件名，不看实际行为变化。
选择提交边界 git add -p
git restore --staged
git commit -m		 要求 Codex 先列 staged / unstaged，然后只暂存本次任务内容。 把格式化、调试、生成物和功能改动混在一个提交。
创建任务分支 git switch -c feature/name
git branch -vv		 让 Codex 解释分支从哪里切出、是否有 upstream。 在错误分支上开发，或基于陈旧 main 开发。
同步远端 git fetch --prune
git pull --ff-only
git push -u origin branch		 让 Codex 先比较本地与远端 ahead/behind，再执行同步。 盲目 pull 产生不必要 merge commit。
恢复与回滚 git restore
git revert
git reflog
git stash		 让 Codex 先给恢复方案对比，确认后再执行有破坏性的操作。 把 reset、clean、force push 当成万能撤销键。
定位回归 git bisect
git blame
git log -S		 让 Codex 设计可重复测试脚本，再用 bisect 二分定位。 凭感觉猜出错提交，浪费时间且不可复现。
并行开发 git worktree add
git worktree list		 让 Codex 在独立 worktree 中处理互不干扰的任务。 多个任务共享同一工作区，改动互相污染。

三、Codex 使用 Git 的标准作战循环

优秀的 Codex 指令不只是“改一下”。它应该给 Codex 一套可执行的边界：先读规则、再看 Git 状态、再改、再验证、最后解释提交范围。

可记作：规则 → 状态 → 边界 → 实作 → 验证 → 提交 → 复盘。这个循环尤其适合多文件改动、线上服务配置、数据库脚本和长期项目维护。

1

先读项目约束

让 Codex 读取 AGENTS.md、README、测试说明、部署说明。项目规则优先于个人习惯。

2

只读建立事实

运行 git status、git diff --stat、git branch -vv，先知道站在哪里。

3

声明提交边界

明确哪些文件属于本次任务，哪些文件是用户已有改动或生成产物，避免混入。

4

小步实现验证

让 Codex 每完成一个行为单元就运行相关测试或静态检查，减少大回滚。

5

审查 staged 内容

提交前必须看 git diff --cached，必要时用 git add -p 精准暂存。

6

写可审阅提交

提交信息写“为什么”和“改了什么”，不要把排障流水账塞进标题。

7

PR 前再对比

用 git diff main...HEAD 看完整分支差异，确认没有带入无关文件。

8

留下复盘证据

最终报告包括改动摘要、验证命令、风险、未完成项。Git 是证据链，不只是存档。

四、交互练习：把抽象命令变成具体动作

下面四个练习覆盖日常最高频场景：选命令、拆提交、理解 merge/rebase、处理冲突。可以直接把生成的 Codex 指令复制到会话里使用。

练习内容是本地页面内模拟，不会修改任何仓库。真正执行前仍应让 Codex 汇报当前 Git 状态。

练习 A：命令选择器

scenario
陌生仓库巡检

先只读，不改文件。目标是建立当前事实：分支、未提交变更、远端、最近提交、风险。

git status --short --branch
git branch -vv
git log --oneline --decorate -5
git diff --stat

练习 B：提交雕刻台

staging

勾选属于同一语义单元的文件，页面会生成建议命令。提交不是“把所有变化打包”，而是“把一个可审阅的意图记录下来”。


              

            

          

        


        

          

            
练习 C：merge 还是 rebase

            

              
              
              
            

          

          

            

              
            

            

              merge：保留分叉事实
              
适合需要保留完整分支上下文的协作场景。历史图会出现 merge commit，审计友好，但线性较弱。

              

                
                
git fetch origin
git switch feature/git-codex
git merge origin/main

              

            

          

        


        

          

            
练习 D：冲突处理模拟器

            

              
              
              
            

          

          

            

              

                
<<<<<<< HEADconst mode = "review";=======const mode = "ship";>>>>>>> feature/release

              

              

                推荐：手动融合
                
当两边都有业务含义时，不要机械选择一边。应理解两个分支的意图，写出第三个正确结果，再运行测试。

              

              

                
                
# 编辑冲突文件，移除冲突标记
git add src/config.ts
git status --short
npm test

              

            

          

        

      

    


    

      

        

          

            
五、恢复排障：Git 的安全绳怎么用

            
恢复类命令要先判断“改动是否已经提交、是否已经推送、是否只是暂存、是否影响他人”。Codex 可以快速生成方案表，但涉及历史重写或删除文件时，必须先确认。

          

          
安全优先级：restore 局部恢复、revert 公开回滚、reflog 找回本地历史、reset --hard 与 clean -fdx 需要极高警惕。

        


        

          

            
恢复决策树

            

              

                
                  
问题优先命令说明

                
                
                  
工作区改错，尚未暂存git restore path恢复单个文件到暂存区或 HEAD 对应状态。

                  
已经暂存，但不想提交git restore --staged path只撤出暂存，不丢工作区修改。

                  
提交了但未推送git reset --soft HEAD~1保留修改，撤回提交。执行前确认分支未共享。

                  
提交已推送，需要撤销git revert SHA生成反向提交，不改写公开历史。

                  
分支或提交找不到git reflog查本地引用移动记录，再创建恢复分支。

                  
想定位回归提交git bisect用自动化测试二分搜索坏提交。

                
              

            

          


          

            
风险雷达

            
勾选准备执行的行为，查看是否应让 Codex 停下来确认。

            

              
              
              
              
              
            

            

            
风险等级：低。可以继续，但仍应保留状态摘要。

          

        

      

    


    

      

        

          

            
六、直接可用的 Codex 指令模板

            
这些模板的核心不是让 Codex “更听话”，而是让任务边界、验证方式和 Git 证据链更明确。复制后替换项目名、目标分支、测试命令即可。

          

          
建议每次复杂任务都加一句：不要改动与本任务无关的已有变更；如发现未预期变更，先报告。

        


        

          

            
            
            
            
            
            
          

          

            
            

          

        

      

    


    

      

        

          

            
七、30 天训练计划：从会用 Git 到会指挥 Codex

            
目标不是把所有命令背下来，而是在真实任务中形成“先观察、再选择、再记录、再复盘”的稳定习惯。勾选状态会保存在当前浏览器。

          

          
推荐节奏：每天 20-30 分钟；每周做一次真实仓库复盘；每次让 Codex 输出 Git 状态表和风险表。

        


        

          

            
第 1 周：基本功

            
目标：一眼看懂当前仓库状态。

            

              
              
              
            

          

          

            
第 2 周：分支协作

            
目标：理解分叉、同步和 PR 差异。

            

              
              
              
            

          

          

            
第 3 周：恢复排障

            
目标：误操作不慌，公开历史不乱改。

            

              
              
              
            

          

          

            
第 4 周：Codex 化

            
目标：把 Git 纳入每次 AI 开发闭环。

            

              
              
              
            

          

        

      

    


    

      

        

          

            
八、三个小测验：判断是否真的掌握

            
能回答这些问题，说明 Git 已经开始从“命令集合”变成“工程判断系统”。

          

        

        

          

            
Q1：为什么提交前要看 git diff --cached？

            
因为工作区和暂存区可能不是同一份内容。

            
            
Git 提交的是暂存区，不是当前工作区。文件可以同时处于 staged 和 unstaged 状态，提交前必须确认即将进入历史的内容。

          

          

            
Q2：已经推送的错误提交，优先用什么撤销？

            
通常优先使用 git revert。

            
            
公开历史应尽量不改写。revert 通过新提交表达反向修改，团队成员同步时更安全。

          

          

            
Q3：Codex 开始改代码前，最应该运行什么？

            
git status --short --branch。

            
            
它能快速暴露当前分支、ahead/behind、暂存区和工作区变化，是避免误碰他人改动的第一道防线。

          

        

      

    

  


  

  
已复制