Git 与协作:把每一次实验都纳入版本控制

Git 与协作:把每一次实验都纳入版本控制

本节摘要:版本控制不是可选项。在这本教程里,你会写下几百个代码文件、跑无数次实验、训练几十个模型——每一行代码、每一次改动都该被追踪。Git 就是干这件事的工具,GitHub 是代码的托管地。本节只讲你过完这门课必须掌握的那一小撮 Git:四区流转的心智模型(工作区 → 暂存区 → 本地仓库 → 远程仓库)、日常三步工作流(add/commit/push)、为隔离实验开分支、写一份能挡掉模型 checkpoint 和大二进制文件的 .gitignore,以及如何 fork 课程仓库、在自己那一份里推进进度。读完本节,你将不再丢失任何一次实验,也能随时回到任意历史时刻。

对应原课程:Phase 00 · Lesson 02 · git-and-collaboration(原英文 phases/00-setup-and-tooling/02-git-and-collaboration/docs/en.md)。前置:第 01 节「开发环境」。

学习目标

阅读完本节,你应当能够:

1. 配置 Git 身份,熟练使用 add、commit、push 这套日常三步工作流。
2. 用分支隔离实验,在不破坏主分支的前提下试错与合并。
3. 写一份合理的 .gitignore,把模型 checkpoint(.pt/.pth/.safetensors)和大二进制文件挡在仓库外。
4. 用 git log 浏览提交历史,理解一个项目的演进脉络。

一、问题与直觉

接下来 20 章里,你会写几百个代码文件。没有版本控制,你会丢东西、改坏东西却撤销不了,也无法与人协作。

工具是 Git,代码放在 GitHub。本节只讲这门课真正需要的那点 Git,不多不少。先理解 Git 的四区流转:

记住三件事就够了:

1. 勤保存:git commit 频繁提交,每个有意义的改动一个 commit。
2. 推到远程:git push 把本地提交同步到 GitHub,既是备份也是协作前提。
3. 实验开分支:git checkout -b experiment,在隔离环境里试错,搞砸了直接删分支。

💡 把 commit 想成「游戏存档」——每个 commit 都是一个你可以随时读档回到的时间点。git push 则是「把存档同步到云端」,机器坏了也不丢。

二、从零实现

Step 1 配置 Git 身份

每台机器配一次,告诉 Git 你是谁:

git config --global user.name "Your Name"
git config --global user.email "you@example.com"
​

Step 2 日常三步工作流

git status                      # 看一眼改了哪些文件
git add file.py                 # 把改动放进暂存区
git commit -m "Add perceptron implementation"   # 存档一个快照
git push origin main            # 推到 GitHub
​

设计要点:commit message 写「这次改动做了什么」,用祈使句(英文)或动宾短语(中文),如「Add 感知机实现」。一年后翻历史,你能一眼看懂自己当时干了啥。

Step 3 为实验开分支

git checkout -b experiment/new-optimizer     # 新建并切到实验分支

# ... 改代码、提交 ...

git checkout main                            # 切回主分支
git merge experiment/new-optimizer           # 满意了就并回主分支
​

实验搞砸了?git checkout main 切回去,git branch -D experiment/new-optimizer 删掉即可,主分支分毫未损。

Step 4 与本课程仓库协作

你不能直接 push 到课程官方仓库——只有维护者有写权限。先在 GitHub 上点右上角 Fork,把仓库 fork 到自己账号下,这样你的 origin 才指向你自己的副本:

git clone https://github.com/YOUR-USERNAME/ai-engineering-from-scratch.git
cd ai-engineering-from-scratch
git checkout -b my-progress       # 在自己的进度分支上推进
# 边学边提交你写的代码
git push origin my-progress
​

Step 5 写 .gitignore(关键)

AI 项目最容易把仓库撑爆的就是模型 checkpoint 和数据集。在仓库根放一份 .gitignore,挡住它们:

# 模型权重 / checkpoint
*.pt
*.pth
*.safetensors
*.ckpt

# 数据集
data/raw/
*.parquet

# Python
__pycache__/
.venv/

# Jupyter
.ipynb_checkpoints/
​

⚠️ 设计警示:一旦大文件被 commit 进去,即便之后再 .gitignore,它的历史也还在仓库里,体积降不下来。务必在第一次 commit 之前就把 .gitignore 配好。已经误提交的,要用 git filter-repo 或 BFG 清理历史。

三、框架对比:你需要的 vs 不需要的

这门课你需要的命令,就下面五条:

就这些。你不需要 rebase、cherry-pick、submodule——那是团队级高级工作流,个人学习用不上。等你以后参与多人开源项目或工业界协作时,再补这些不迟。

四、可复用产物

本节产出一个可复用模板(原课程 outputs/):

• 一份 .gitignore 模板:覆盖 Python、Jupyter、模型权重、数据集这四类常见垃圾文件。任何新 AI 项目都能直接复制使用,按需增删几行即可。

五、练习

1. (Easy) Fork 本课程仓库,clone 你的 fork,新建一个分支叫 my-progress,在里面新建一个文件、提交、push 到你自己的 GitHub。
2. (Medium) 写一份 .gitignore,把模型 checkpoint(.pt、.pth、.safetensors)排除在外;再用 git rm --cached 把一个误提交的 checkpoint 移出追踪(保留本地文件)。
3. (Hard) 用 git log --oneline 浏览本课程仓库的历史,挑一段连续的 commit,读出这一段课程内容是如何被逐步添加进来的;再用 git checkout <某个旧 commit> 把项目切回那个时间点跑一下代码,体感「随时读档」的威力。

本节要点回顾

1. 版本控制非可选:几百个文件、无数次实验,没有 Git 就会丢东西、改坏却无法撤销。
2. 四区流转:工作区 →(add)→ 暂存区 →(commit)→ 本地仓库 →(push)→ 远程仓库;反向是 fetch/pull。
3. 日常三步:add(放进暂存)→ commit(存档快照)→ push(同步到 GitHub)。
4. 实验开分支:checkout -b 在隔离分支试错,搞砸了删分支,主分支安全。
5. .gitignore 越早写越好:挡住 checkpoint 与大二进制;误提交后清历史代价高。
6. Fork 才能推送:你 fork 课程仓库到自己的账号,origin 才指向你能写的副本。
7. 本课只需五条命令:clone、add/commit、push、checkout -b、log——rebase、cherry-pick 这些个人学习用不上。

下一节,我们将进入「GPU 配置与云端」——从单机环境扩展到 GPU 加速与云端算力,为训练密集的课备好算力。