Git 要求与临时仓库 —— 为什么 Codex CLI 必须在 Git 里跑？

简介

如果你尝试在一个没有 Git 的目录中运行 Codex CLI，你很可能会看到这样一条错误信息：

text

❌ Error: Not a git repository.
   Please run 'git init' in the current directory first.

很多第一次接触 Codex CLI 的开发者都会感到困惑：AI 帮我写代码，跟 Git 有什么关系？为什么非要 Git 仓库才能跑？

这恰恰是理解 Codex CLI 设计哲学的关键所在。Git 不仅是 Codex CLI 的"硬性要求"，更是其安全体系、上下文管理和回滚机制的基石。本文将深入解释这一切。

一、为什么必须在 Git 仓库中运行？

1.1 核心原因一：变更追踪

Codex CLI 的核心价值是"让 AI 自动修改你的代码"。但 AI 改了什么？改得对不对？如果改错了怎么办？

Git 提供了答案。

bash

# AI 修改后的变更一览
git diff

# 具体到某个文件
git diff src/models/User.js

# 查看变更统计
git diff --stat

如果没有 Git，AI 直接在文件系统上修改代码，你将无法追踪到底改了什么——这对开发者来说是不可接受的。

1.2 核心原因二：安全回滚

AI 不是完美的。它可能写出有 Bug 的代码，可能误解你的意图，可能做出你不想要的改动。

有了 Git，回滚只需一条命令：

bash

# 不满意 AI 的修改？一键回滚
git checkout .

# 或者回滚到 AI 修改之前的状态
git reset --hard HEAD

# 只回滚某个文件
git checkout -- src/models/User.js

没有 Git 就没有回滚保障，而 Codex CLI 不能在没有安全保障的情况下修改用户的文件。

1.3 核心原因三：上下文提供

Git 历史是理解项目演变的最佳窗口。Codex CLI 可以利用 Git 历史来：

理解项目的编码风格和约定
查看最近的修改和决策
识别哪些文件是核心、哪些是辅助
理解项目的技术演进方向

bash

# AI 可能会执行以下命令来理解项目
git log --oneline -20           # 最近的提交历史
git log --follow src/app.js     # 某个文件的修改历史
git show HEAD:src/config.js     # 查看某个文件的内容
git blame src/utils.js          # 谁在什么时候修改了什么

1.4 核心原因四：状态快照

在 AI 开始工作之前，Codex CLI 可以通过 Git 创建一个干净的状态快照：

text

┌────────────────────────────────────────────────────────┐
│                  Codex CLI + Git 工作流程                 │
│                                                        │
│  1. 检查点: git status                                 │
│     ↓                                                  │
│     确认工作目录干净（或提醒先提交）                       │
│     ↓                                                  │
│  2. 快照: git stash 或 git commit                      │
│     ↓                                                  │
│     保存当前状态作为回滚点                               │
│     ↓                                                  │
│  3. AI 工作: codex exec "任务"                          │
│     ↓                                                  │
│     在沙箱中创建/修改文件，同步到工作目录                  │
│     ↓                                                  │
│  4. 审查: git diff                                     │
│     ↓                                                  │
│     查看 AI 做了什么改动                                 │
│     ↓                                                  │
│  5. 决定: 满意 → git commit                             │
│           不满意 → git checkout                        │
│                                                        │
└────────────────────────────────────────────────────────┘

二、Git 错误排查

2.1 常见错误

错误 1：当前目录不是 Git 仓库

bash

codex "写一个 Python 脚本"
# ❌ Error: Not a git repository.
#    Please run 'git init' in the current directory first.

解决方案：

bash

git init
git add .
git commit -m "Initial commit"
codex "写一个 Python 脚本"

错误 2：有未提交的更改

某些版本的 Codex CLI 可能要求工作目录干净：

text

⚠️ Warning: Working directory has uncommitted changes.
   Consider committing or stashing before running Codex.

解决方案：

bash

# 方案 A：提交当前更改
git add .
git commit -m "Save current state before Codex"

# 方案 B：暂存更改
git stash

# 运行 Codex 后再恢复
git stash pop

错误 3：Git 未安装

bash

bash: git: command not found

解决方案：

bash

# macOS
brew install git

# Ubuntu / Debian
sudo apt update && sudo apt install -y git

# CentOS / RHEL
sudo yum install -y git

# Windows (Git Bash / WSL)
# 安装 Git for Windows: https://git-scm.com/download/win

2.2 Git 配置检查

bash

# 检查 Git 配置
git config --list

# 确保 user.name 和 user.email 已设置
git config --global user.name "Your Name"
git config --global user.email "your.email@example.com"

# 检查默认分支名称
git config --global init.defaultBranch main

三、`git init` Scratch 模式

3.1 什么是 Scratch 模式？

Scratch（画板）模式是指在 全新的、空白的 Git 仓库 中运行 Codex CLI。这是最安全、最干净的 Codex CLI 使用方式。

bash

# 创建一个 scratch 目录
mkdir -p ~/codex-scratch && cd ~/codex-scratch

# 初始化为 Git 仓库
git init
# 输出: Initialized empty Git repository in /home/user/codex-scratch/.git/

# 创建初始提交（有些版本需要至少一个提交）
echo "# Codex Scratch" > README.md
git add .
git commit -m "Initial commit"

# 开始使用 Codex
codex "创建一个 React + TypeScript 项目"

3.2 为什么推荐 Scratch 模式？

优势	说明
零风险	不会影响任何现有项目
干净环境	没有历史包袱，AI 从零开始
快速实验	试错了就删掉重来
完整追踪	每次 AI 操作都有清晰的 Git 历史
可复制	实验成功后，可以将代码迁移到正式项目

3.3 Scratch 模式脚本

你可以创建一个脚本来快速启动 Scratch 环境：

bash

#!/bin/bash
# codex-scratch.sh —— 快速创建 Codex 临时仓库

set -e

# 创建临时目录
SCRATCH_DIR=$(mktemp -d ~/codex-scratch-XXXXXX)

echo "📁 创建临时工作目录: $SCRATCH_DIR"
cd "$SCRATCH_DIR"

# 初始化 Git 仓库
git init
echo "# Codex Scratch Project" > README.md
echo "Created: $(date)" >> README.md
git add .
git commit -m "🎯 Initial commit"

echo "✅ Scratch 环境已就绪!"
echo "📍 目录: $SCRATCH_DIR"
echo "💡 运行 codex 开始编码:"
echo "   codex '你的任务描述'"
echo ""
echo "🗑️ 用完后可删除: rm -rf $SCRATCH_DIR"

使用方式：

bash

# 创建脚本
chmod +x ~/bin/codex-scratch.sh

# 启动 scratch 环境
~/bin/codex-scratch.sh
# 输出: 📁 创建临时工作目录: /home/user/codex-scratch-a1b2c3
# 输出: ✅ Scratch 环境已就绪!
# 输出: 💡 运行 codex 开始编码

# 在新目录中执行 Codex
codex "创建一个 Express API 服务器"

3.4 自动化 Scratch + Codex

更进一步，你可以将 Scratch 创建和 Codex 执行合并：

bash

#!/bin/bash
# codex-scratch-run.sh —— 创建 scratch 并立即执行 Codex

set -e

TASK="$1"

if [ -z "$TASK" ]; then
  echo "用法: codex-scratch-run.sh '任务描述'"
  exit 1
fi

SCRATCH_DIR=$(mktemp -d ~/codex-scratch-XXXXXX)
cd "$SCRATCH_DIR"

git init
echo "# Codex Project: $TASK" > README.md
git add .
git commit -m "🎯 Initial commit"

echo "🚀 在 Scratch 环境中执行 Codex..."
echo "📍 目录: $SCRATCH_DIR"
echo ""

codex --sandbox full-auto "$TASK"

echo ""
echo "✅ 任务完成!"
echo "📂 结果在: $SCRATCH_DIR"
echo "📊 查看变更: cd $SCRATCH_DIR && git diff"

使用方式：

bash

chmod +x ~/bin/codex-scratch-run.sh
~/bin/codex-scratch-run.sh "创建一个 Python Flask 博客应用"

四、Git 在 Codex CLI 中的进阶用法

4.1 利用 Git 历史作为上下文

Codex CLI 可以利用 Git 历史来更好地理解你的项目：

bash

# 让 AI 分析最近的改动
codex "分析最近的 5 次提交，总结项目的主要变更趋势"

# 让 AI 查看某个分支的改动
codex --sandbox full-auto "查看 feature/auth 分支的改动，合并到 main 时需要注意什么"

# 让 AI 基于 Git 历史生成变更日志
codex "根据 Git 历史生成 CHANGELOG.md，遵循 Keep a Changelog 格式"

4.2 Git 钩子与 Codex CLI 的集成

你可以将 Codex CLI 集成到 Git 钩子中：

bash

# .git/hooks/commit-msg —— 使用 AI 优化提交信息
#!/bin/sh
COMMIT_MSG_FILE=$1
COMMIT_MSG=$(cat "$COMMIT_MSG_FILE")

# 如果提交信息太短，让 AI 优化
if [ ${#COMMIT_MSG} -lt 20 ]; then
  echo "🤖 让 AI 优化提交信息..."
  NEW_MSG=$(codex --sandbox full-auto "将以下提交信息优化为 Conventional Commits 格式: $COMMIT_MSG")
  echo "$NEW_MSG" > "$COMMIT_MSG_FILE"
fi

bash

# .git/hooks/pre-commit —— 让 AI 检查代码质量
#!/bin/sh
echo "🤖 让 AI 检查代码变更..."
git diff --cached | codex --sandbox full-auto "分析这个 diff，检查是否有潜在的 Bug 或代码质量问题"

4.3 分支策略与 Codex CLI

bash

# 为每个 Codex 任务创建独立分支
git checkout -b codex/add-user-auth
codex "实现用户认证功能"

# 审查 AI 的改动
git diff main

# 满意后合并
git checkout main
git merge codex/add-user-auth

# 不满意就丢弃
git branch -D codex/add-user-auth
git checkout main

4.4 Git Bisect 与 Codex CLI

当 AI 引入了一个 Bug 时，可以使用 git bisect 定位问题：

bash

git bisect start
git bisect bad HEAD            # 当前版本有 Bug
git bisect good v1.0.0         # v1.0.0 是正常的

# 然后让 AI 自动测试每个版本
git bisect run codex "运行测试并判断是否通过"

五、临时仓库的最佳实践

5.1 何时使用临时仓库？

bash

# ✅ 适合使用临时仓库的场景

# 1. 快速原型验证
mkdir -p /tmp/prototype && cd /tmp/prototype && git init
codex "创建一个实时聊天应用"

# 2. 学习新技术
mkdir -p ~/learn-svelte && cd ~/learn-svelte && git init
codex "用 SvelteKit 创建一个待办事项应用"

# 3. 测试 AI 能力
mkdir -p ~/test-codex && cd ~/test-codex && git init
codex "用 10 种不同的方式实现快速排序"

# 4. 代码片段实验
mkdir -p ~/code-snippets && cd ~/code-snippets && git init
codex "写一个正则表达式来验证邮箱地址"

5.2 临时仓库的生命周期管理

bash

# 创建
mkdir -p ~/codex-temp/my-experiment && cd ~/codex-temp/my-experiment
git init

# 工作
codex "创建项目"

# 保存成果（如果满意）
git add .
git commit -m "实验成果"

# 方案 A：迁移到正式项目
cp -r ~/codex-temp/my-experiment/src ~/real-project/src/

# 方案 B：克隆到正式仓库
cd ~/real-project
git remote add experiment ~/codex-temp/my-experiment
git fetch experiment
git merge experiment/main

# 清理
rm -rf ~/codex-temp/my-experiment

5.3 自动化临时仓库清理

bash

# 添加一个 cron 任务或脚本来清理过期的临时仓库
#!/bin/bash
# clean-codex-scratch.sh

SCRATCH_DIR=~/codex-scratch-*
THRESHOLD_DAYS=7

find ~/ -maxdepth 1 -name "codex-scratch-*" -type d -mtime +$THRESHOLD_DAYS | while read dir; do
  echo "🗑️ 清理过期的 Scratch 目录: $dir"
  rm -rf "$dir"
done

echo "✅ 清理完成"

六、与其他 AI 工具的对比

工具	需要 Git	回滚机制	上下文来源
Codex CLI	✅ 必须	Git checkout	Git 历史 + 文件
GitHub Copilot	❌ 不需要	手动撤销	当前文件 + 编辑器
Cursor	❌ 不需要	编辑器撤销	工作区文件
Claude Code	✅ 推荐	Git / 手动	Git 历史 + 文件
Aider	✅ 必须	Git commit	Git 历史

Codex CLI 对 Git 的强依赖不是缺陷，而是 设计哲学：

每一个 AI 生成的改动都应该是可追踪、可审查、可回滚的。

这与企业级软件开发的最佳实践完全一致。

七、常见问题 FAQ

Q1：我可以在已有项目的子目录中运行 Codex CLI 吗？

A：可以。Codex CLI 只需要当前目录或其父目录中有 .git 即可：

bash

# 在项目根目录初始化 Git
cd ~/my-project
git init

# 在任何子目录中运行 Codex
cd ~/my-project/src
codex "优化这个模块的性能"

Q2：我不想把 AI 生成的代码提交到 Git，可以吗？

A：完全可以。Git 只是用来追踪变更和提供回滚能力。你可以：

bash

# 使用 .gitignore 排除 AI 生成的文件
echo "ai-generated/" >> .gitignore

# 或者使用单独的分支
git checkout -b ai-experiments
# 在这个分支上工作，不合并到主分支

Q3：Codex CLI 会自动提交代码吗？

A：默认不会。Codex CLI 只负责在沙箱中生成和修改文件，然后同步到你的工作目录。是否提交完全由你决定。

Q4：Git 仓库太大，Codex CLI 会变慢吗？

A：Codex CLI 主要关注工作目录中的文件，不会遍历整个 Git 历史。但如果你使用了 --file 选项附加了很多文件，可能会影响性能。建议：

bash

# 在大型仓库中，指定具体的工作目录
cd ~/my-project/src
codex "优化当前目录的代码"
# 而不是在根目录运行整个仓库

Q5：我可以禁用 Git 检查吗？

A：当前版本不支持。这是 Codex CLI 的核心安全要求，无法绕过。如果确实需要在无 Git 环境中使用 AI 编码工具，可以考虑其他工具。

八、实战演练：从零到完整项目

让我们用一个完整的实战来巩固今天学到的知识：

bash

# 步骤 1：创建 scratch 环境
mkdir -p ~/codex-workshop && cd ~/codex-workshop
git init

# 步骤 2：初始提交
echo "# Codex Workshop" > README.md
git add .
git commit -m "🎯 Workshop start"

# 步骤 3：生成项目骨架
codex --sandbox full-auto "创建一个 Node.js + Express + SQLite 的博客 API，包含：
- 用户注册和登录（JWT 认证）
- 文章的 CRUD 操作
- 评论功能
- 使用 Jest 编写测试
- 使用 ESLint 和 Prettier"

# 步骤 4：审查 AI 的改动
git status
git diff --stat
git log --oneline

# 步骤 5：运行测试
npm test

# 步骤 6：提交成果
git add .
git commit -m "$(codex --sandbox full-auto "根据当前的 Git diff 生成一个详细的提交信息")"

# 步骤 7：查看最终状态
git log --oneline --graph
echo "✅ 项目完成！"

总结

本文深入探讨了 Codex CLI 对 Git 的依赖关系：

四大原因：变更追踪、安全回滚、上下文提供、状态快照
错误排查：常见的 Git 相关错误及解决方案
Scratch 模式：在干净的临时仓库中安全地实验和开发
自动化脚本：一键创建 Scratch 环境并执行 Codex 任务
进阶用法：Git 钩子集成、分支策略、Bisect 定位
最佳实践：临时仓库的生命周期管理
设计哲学：可追踪、可审查、可回滚的企业级标准

Git 不是 Codex CLI 的"额外要求"，而是其 安全体系的核心组成部分。理解了这一点，你就理解了为什么 Codex CLI 被设计为"AI Agent"而不仅仅是"代码生成器"。

下篇预告

本系列文章到这里已经覆盖了 Codex CLI 的安装认证、核心命令、沙箱安全和 Git 集成。

下一篇我们将进入 模型选择与成本优化。你将学习：

Codex CLI 支持哪些模型？o3、o4-mini、o3-pro 各有什么特点？
如何在效果和成本之间找到最佳平衡？
自定义模型提供商（Custom Providers）的配置方法
实用技巧：用更便宜的模型完成 80% 的任务

敬请期待！