# Codex 代码管理:Git 与 GitHub

> 用 Codex 做真实项目必知的 Git/GitHub 核心概念与工作流,含 Worktree 隔离实验。

URL: https://docs.passion8.cc/docs/codex/git
Language: zh-CN
Publisher: Passion8

用 Codex 做真实项目,迟早要和 Git、GitHub 打交道。一句话拆清楚三者关系:**Git 记录本地代码变化,GitHub 远程保存与协作,Codex 完成具体的编程任务。** 懂这套组合,改错能回退,实验能隔离,协作能走 PR。

## Git vs GitHub

| 维度 | Git | GitHub |
| --- | --- | --- |
| 本质 | 本地版本管理工具 | 代码云端存储 + 协作平台 |
| 运行位置 | 你的电脑 | 浏览器 / 云端 |
| 核心操作 | commit、branch、diff、merge | repository、issue、PR、Actions |
| 网络要求 | 不需要 | 需要 |
| 与 Codex 的关系 | Codex 改完后用 Git 检查和保存 | Codex Web/Cloud 版常与 GitHub 配合 |

## 必懂 Git 概念

| 概念 | 含义 |
| --- | --- |
| Repository | 代码仓库,存放整个项目及其历史 |
| Commit | 一次存档,记录这次改了什么 |
| Branch | 分支,独立开发线,不影响主线 |
| Diff | 改动对比,看具体变了哪些行 |
| Stage | 暂存区,commit 前先把改动放进来 |
| Merge | 把一条分支的改动合并到另一条 |
| Conflict | 冲突,两边改了同一处,需手动选择保留哪个 |
| Push | 把本地 commit 推送到远端 |
| Pull | 把远端更新拉取同步到本地 |
| Clone | 把远端仓库完整下载到本地 |

## 必懂 GitHub 概念

| 概念 | 含义 |
| --- | --- |
| Repository | 项目仓库,云端版的 Git repo |
| Issue | 问题与需求的记录单 |
| Pull Request (PR) | 代码合并申请,方便 review 后再合入主线 |
| Main Branch | 主分支,存放稳定可用版本 |
| Feature Branch | 功能分支,开发新功能时使用 |
| Review | 代码审查,合并前检查 |
| Actions | 自动化流程,触发测试 / 构建 / 部署 |
| README | 项目说明文档 |
| .gitignore | 忽略文件清单,防止上传无关或敏感文件 |

## 为什么用 Codex 更需要 Git

Codex 每次任务可能改动大量文件。没有版本控制,出错很难回头;有了 Git:

- **可审查**:Codex 改完用 `git diff` 看到底动了哪里
- **可回退**:改坏了,找到上一个好的 commit 恢复
- **可分阶段**:多步改动每步 commit,进度清晰
- **可隔离实验**:用 branch 或 worktree 让 Codex 大胆试,主线不受影响
- **可协作**:push 到 GitHub,走 PR / review / merge 流程




没有 Git 保底,让 Codex 大改会很焦虑。有了 commit 记录,随时可以检查和还原,才能放心给它更大权限。




## 在 Codex 里用 Git 的标准流程







### 初始化仓库

在项目根目录运行 `git init`,把项目纳入版本控制。






### 写好 .gitignore

告诉 Codex:"帮我写一份 .gitignore,排除 node_modules、.env 和其他不需要追踪的文件。"它会根据技术栈生成合适的清单。






### 首次 commit

在 Codex 动任何东西之前,先保存一个干净的初始版本:`git add -A && git commit -m "init"`。



![在 Codex 中初始化 Git](https://docs.passion8.cc/images/codex/image-049-1201459d2a.png)




### 新建任务分支

每个任务单独开分支,比如 `git checkout -b feat/add-login`。这样即便 Codex 改坏,主线也不受影响。






### 让 Codex 实现需求

在对话框描述目标,让它读代码、写代码、跑命令。






### 查看 diff

Codex 完成后,在终端运行 `git diff` 或在 IDE 里查看改动,确认符合预期。






### 运行验证

跑测试或启动项目确认功能正常,有问题继续让 Codex 修。






### Commit 保存

满意后:`git add -A && git commit -m "feat: 描述这次改动"`。






### Push 到 GitHub

`git push origin feat/add-login`,把分支推到远端备份。






### 创建 PR

在 GitHub 上从功能分支发起 Pull Request,review 通过后合入主线。






## 上传到 GitHub 的前提

| 准备项 | 说明 |
| --- | --- |
| GitHub 账号 | 注册并登录 |
| 本地 Git | 已安装并 `git init` |
| GitHub 仓库 | 在 GitHub 新建 Repository,复制地址 |
| 认证 | 配好 SSH Key 或 Personal Access Token |
| .gitignore | 确认敏感文件已排除 |

把仓库地址发给 Codex,告诉它:"把当前项目推到这个 GitHub 仓库",它会处理 `remote add` 和首次 `push`。

## 代码回滚







### 找到目标版本

运行 `git log --oneline` 或在 IDE 的 Git 面板里查看历史,找到想恢复的那次 commit,复制 commit 哈希(如 `a3f8c12`)。






### 告诉 Codex 回退

把哈希粘贴给 Codex:"帮我回退到 commit `a3f8c12`,保留这之后的改动作为未提交状态。"它会根据你的需求选择合适的 git 命令。









强制回退(`git reset --hard`)会丢失未提交的改动。让 Codex 操作前先确认当前工作区已 commit 或 stash。




## Git Worktree:给 Codex 开独立草稿本

普通分支切换时,整个工作目录会跟着变。**Worktree** 让你在同一个 Git 仓库里同时维护多个独立的工作目录——相当于给项目开了几个互不干扰的草稿本。

### 为什么需要 Worktree

| 场景 | 说明 |
| --- | --- |
| 让 Codex 大胆改 | 单独副本实验,主项目目录完全不动 |
| 并行多任务 | 每个任务一个 worktree,互不阻塞 |
| 方案对比 | A / B / C 方案各一个目录,直观比较 |
| 快速丢弃 | 实验改坏了,直接删掉这个 worktree |
| 大规模重构 | 在隔离副本里重构,满意后再合并,不污染主线 |

### 基本用法

```bash
# 在主仓库旁边创建一个新的工作副本,关联到新分支
git worktree add -b feat/experiment ../my-project-experiment

# 查看当前所有 worktree
git worktree list

# 实验完毕,合并分支后删除 worktree
git worktree remove ../my-project-experiment
git branch -d feat/experiment
```

**典型流程**:在主目录正常工作 → 开新 worktree 交给 Codex 实验 → Codex 改好后 `git diff` 审查 → 满意就合并回主线,不满意直接 `git worktree remove` 扔掉,主项目分毫未动。

![Git Worktree](https://docs.passion8.cc/images/codex/image-060-1e3fd3edad.png)




把 worktree 路径告诉 Codex,让它在那个目录里工作:`cd ../my-project-experiment && codex "..."`,或在对话里说明当前工作目录。