Git 与 GitHub / Gitee

写代码最怕三件事：改坏了回不去、不知道改了哪里、多人协作文件冲突。Git 解决的就是这三个问题：

• 记录每次改动：谁、什么时间、改了什么、为什么改
• 随时回退：写坏了？一条命令回到昨天的版本
• 并行开发：用分支同时尝试多个方案，互不干扰
• AI 时代的必需品：AI 会快速生成大量代码，Git 帮你追踪和回退

如果你还在用 代码_v1.py、代码_v2_最终.py、代码_v3_真的最终.py，Git 就是救星。

sudo apt install git
git --version

# 配置身份（会出现在每次提交记录里）
git config --global user.name "你的名字"
git config --global user.email "你的GitHub邮箱"
git config --global init.defaultBranch main

90% 的情况你只需要这四个操作：

git clone git@github.com:用户名/仓库名.git   # ① 下载项目到本地
# ... 写代码 ...
git add .                                      # ② 暂存所有改动
git commit -m "feat: 添加了用户登录功能"       # ③ 提交（拍照存档）
git push                                       # ④ 推送到 GitHub

Commit message 格式推荐：type: 简短描述。type = feat（新功能）、fix（修复）、docs（文档）、refactor（重构）。

注册

github.com → Sign up → 用 SEU 邮箱注册（后续能领 GitHub Student Developer Pack，免费获得几十种开发者工具）

配 SSH Key（免密码推送）

# 生成密钥
ssh-keygen -t ed25519 -C "你的GitHub邮箱"
# 一路回车

# 查看公钥
cat ~/.ssh/id_ed25519.pub

# 复制输出全部内容 → GitHub → Settings → SSH and GPG keys → New SSH key → 粘贴
# 验证
ssh -T git@github.com
# 看到 "Hi xxx!" 即成功

之后 git clone 用 SSH 地址（git@github.com:...）而不是 HTTPS，不用每次输密码。

GitHub 的访问在国内不稳定，有时打不开或速度极慢。Gitee（码云）是国内对标平台，功能相似但无需翻墙，访问流畅。

注册与配置

gitee.com 注册（可用手机号）→ 设置 → SSH 公钥，步骤和 GitHub 一致：

ssh-keygen -t ed25519 -C "你的邮箱"
cat ~/.ssh/id_ed25519.pub
# 复制 → Gitee → 设置 → SSH 公钥 → 粘贴
ssh -T git@gitee.com

GitHub vs Gitee

两个都注册。GitHub 用来领 Student Pack 和参与开源，Gitee 用来放日常作业和国内访问的项目。

推荐日常用 VS Code 图形界面，命令行作为参考：

• 暂存：左侧 Source Control 面板（Ctrl+Shift+G），文件名悬停点 +

• 提交：输入 commit message → 点 ✓
• 推送/拉取：点 Sync Changes
• 查看历史：装 GitLens 扩展，可视化每次提交的改动
• 撤销：右键文件 → Discard Changes

有些东西绝对不能上传：

# Python
.venv/
__pycache__/
*.pyc

# 密钥文件（绝对不能上传！）
.env
.env.local

# Node.js
node_modules/

# 编辑器
.DS_Store

⚠️ API Key 永远不要上传到 GitHub，即使是私有仓库。一旦上传，Git 历史永久保留，删文件也没用。Key 泄露了立刻在平台上删除并重新生成。

基本循环

git add . && git commit -m "checkpoint: 大改动前存档"   # ① 开始前存档
# ... AI 写代码 ...
git diff                                                  # ② 看 AI 改了什么
git add . && git commit -m "feat: AI 辅助完成 xxx"       # ③ 满意就提交
git reset --hard HEAD                                     # ④ 不满意一键回退

Claude Code 内置 Git 感知，可以直接对它说「回退到上一个 commit」「帮我写一条 commit message」。

Checkpoint Commit：存盘习惯

AI 写代码节奏快——几分钟能产出你手写几小时的量。问题是：AI 可能中途跑偏，等你发现时已经改了几十个文件。

每隔 10-15 分钟存档一次，不等到全部完成再提交：

① 完成数据模型定义 → git commit -m "checkpoint: 数据模型"
② 完成核心逻辑     → git commit -m "checkpoint: 核心逻辑"
③ 完成测试         → git commit -m "checkpoint: 测试"

好处：AI 跑偏了 → 回退到最近 checkpoint 重来。任务中断了 → 下次从最近的 checkpoint 继续。

Atomic Commit：一个提交只做一件事

AI 有时候一次改太多——修 bug 顺手改了格式化、重构了变量名、升级了依赖，全混在一个 commit。出问题时 git revert 会撤掉太多无关改动。

原子提交 = 一个 commit 只表达一个可理解的语义变化。

Checkpoint 负责进度保存（可以 messy），合并前整理成 Atomic commit（整洁可回滚）。两者互补——checkpoint 保现场，atomic 保质量。

Commit Trailer：让 AI 的决策留在历史里

Git 只记录代码变更，不记录「为什么这样改」「AI 是怎么决策的」。Commit trailer 是 Git 内置的结构化键值对机制（和 Co-authored-by、Signed-off-by 同类），格式为 Key: Value，放在 commit message 末尾。

推荐的 trailer 字段：

完整示例：

feat(auth): implement JWT refresh token rotation

Add sliding-window refresh token support to reduce re-login friction
while maintaining session security.

Agent-Task: PROJ-234 - Add refresh token support
Agent-Model: Kimi-K2.5
Agent-Decision: Used 7-day sliding window over fixed expiry for better UX;
refresh tokens stored in httpOnly cookie to prevent XSS access
Agent-Limitation: Redis TTL not yet aligned with token expiry on logout

可以用标准 Git 命令查询 trailer：

git log --format='%(trailers:key=Agent-Task,valueonly)'  # 列出所有任务 ID
git log --grep="^Agent-Task:" --all                       # 按任务过滤提交

让 AI 写 trailer：在 system prompt 或 AGENT.md 中要求上述格式。一周后回来看 Git 历史，每条 commit 都告诉你 AI 做了什么、用什么模型、为什么这样决策。

Worktree：让多个 AI 互不干扰

一个项目同时开两个 AI 干活 → 文件互相覆盖 → 灾难。

Git Worktree 解决这个问题：在同一个 .git 仓库上创建多个独立工作目录：

git worktree add ../myproject-agent2 -b agent/task-002

Claude Code 创建 worktree 时可以自动隔离。当两个 AI 同时干活时，让它们各占一个 worktree。

Feature Branch：禁止直接 push main

让 AI 直接往 main 分支提交是灾难的起点。铁律：AI 永远在独立分支上工作，合并必须经过人工审查。

# AI 每次执行新任务前，从最新的 main 切出新分支
git checkout main && git pull
git checkout -b agent/task-xxx

# 用 GitHub/Gitee 的 Branch Protection：
# Settings → Branches → Add rule → main
# ✅ Require a pull request before merging
# ✅ Require approvals: 1

分支命名规范：agent/<任务简述>，一眼能看出是 AI 干的。不要在同一分支上执行多个不相关的 AI 任务。

Interactive Rebase：整理 AI 的提交历史

AI 在工作过程中会留下大量 [WIP] checkpoint commit。合并到 main 之前，把这些碎片整理成有意义的 atomic commit，让历史可读。

# 查看当前分支相对于 main 的提交
git log --oneline main..HEAD

# 交互式 rebase 整理最近 N 个提交
git rebase -i main

# 常用操作：
# pick   - 保留该提交
# squash - 合并到上一个提交
# reword - 修改 commit message
# drop   - 删除该提交

整理策略：把 checkpoint commit 合并（squash）为语义清晰的 atomic commit，确保最终历史中每个 commit 都能独立理解和回滚。这件事本身也可以交给 AI 做：

对 AI 说：「帮我整理当前分支相对于 main 的提交历史，把 [WIP] checkpoint 合并为 atomic commit，每个 commit 加上 Agent-Task 和 Agent-Decision trailer。」

Jujutsu 与 GitButler：下一代 Git？

Jujutsu（jj）是 Google 工程师开发的 Git 兼容工具，在 AI 编程社区越来越火。

为什么 AI 编程用户喜欢它：

完全兼容 Git，jj git init --colocate 在已有仓库中启用，GitHub / Gitee 照常用。

GitButler 是另一个值得关注的新工具，定位为 AI 驱动开发重新设计的版本控制客户端。核心创新是虚拟分支（Virtual Branches）：多个分支共享同一个工作目录，按代码块（hunk）粒度将改动自动归类到不同分支。多个 AI 同时干活时，不需要手动创建 worktree，GitButler 自动隔离。底层仍然是标准 Git 仓库，兼容所有现有工具链。

大一新生建议：先掌握 Git 四步基本操作。做 AI 项目多了觉得 Git 不够顺手时，再来了解 Jujutsu 或 GitButler。

GitHub 上开源项目很多，但"开源"不等于"能用"。找到一个仓库后，快速判断它是否值得投入时间：

只选"活的、跑得通的"baseline，不要因为 repo 开源就相信它能用。工程时间砸在配一个死仓库上，是本科科研最常见的低效投入。