test-repo/docs/zh-cn/appendix/2-development-tools/git-version-control.md

Git：代码的时光机

::: tip 🎯 核心问题 写代码时最怕什么? 写错了想回退、改崩了想重来、多人同时改同一个文件...这些头疼的事,Git 都能帮你搞定!它就像是代码世界的"时光机",让你随时回到过去,又能和队友在各自的"平行宇宙"里安全开发。 :::

---

0. 最常用的 5 个场景(直接照抄)

如果你只想"立刻能用",先把这块过一遍:每个场景都是现实工作中最常见的 Git 流程。

---

1. 为什么要学 Git?三大痛点

1.1 痛点一:版本混乱

你是否经历过这种绝望?

论文_初稿.doc
论文_修改版.doc
论文_最终版.doc
论文_最终版_打死不改版.doc
论文_绝对是最后一次修改版.doc

Git 的解决方案:不需要复制副本,一个文件夹搞定所有历史版本。想回到哪次修改,一键恢复。

1.2 痛点二:无法后悔

::: tip 💡 这个场景你一定遇到过 写代码写了 3 小时,突然发现之前的思路更好,但已经改不回去了...或者删错了一段代码,想找回原来的版本。

有了 Git,这种情况永远不会发生。每次重要节点都能"存档",出问题随时"读档"重来。 :::

1.3 痛点三:协作冲突

你和队友同时改同一个文件:

• 你改了 A 文件的第 10 行
• 队友改了 A 文件的第 15 行
• 怎么合并?谁覆盖谁?

Git 的解决方案:智能合并,自动处理大部分冲突。只有当你们真的改了同一行代码时,才需要手动决定用谁的。

---

2. 核心概念:三区模型

Git 的设计哲学其实很像寄快递。

2.1 三个区域是什么?

::: tip 📦 用快递理解 Git 想象你在寄快递:

• 工作区(Working Dir) = 你的书桌。你在这里整理要寄的东西,想怎么乱改都行。
• 暂存区(Staging Area) = 快递盒。你把要寄的文件放进去(git add),准备打包。
• 仓库(Repository) = 快递柜。一旦你封箱寄出(git commit),这个版本就被永久记录下来了。 :::

区域	作用	对应命令	状态
工作区	你当前正在改的代码	git status 查看修改	红色 = 未暂存
暂存区	准备提交的文件	git add 添加	绿色 = 已暂存
仓库	永久保存的历史版本	git commit 提交	只读,不能改

::: tip 💡 关键理解 只有提交到仓库的内容才是安全的。工作区里没提交的内容,丢了就真丢了。所以经常git commit是好习惯! :::

---

3. 基础工作流:存档三步走

日常开发中,你 90% 的时间都在重复这三个动作。

3.1 第一步:修改代码(工作区)

在工作区写写画画,想怎么改就怎么改。这时候修改只在你本地,还没记录。

3.2 第二步:挑选文件(git add → 暂存区)

::: tip 🤔 为什么要先 add 再 commit? 你可能问:为什么不能直接 commit 所有修改?

答案:因为有时候你不想一次性提交所有改动。

• 今天改了 5 个文件,但只想提交其中 3 个(完成了一个功能)
• 另外 2 个文件还在调试中,不想现在提交

git add 让你有选择权:决定这次提交包含哪些文件。 :::

常用命令:

# 添加单个文件
git add index.html

# 添加所有修改
git add .

# 查看哪些文件被暂存了
git status

3.3 第三步:封箱提交(git commit → 仓库)

给这次修改起个名字(比如"修复了登录 Bug"),永久存档。

重要:commit message 要写清楚!

# ❌ 不好的写法
git commit -m "update"

# ✅ 好的写法
git commit -m "feat: 添加用户登录功能"
git commit -m "fix: 修复首页在 iOS 的显示问题"
git commit -m "docs: 更新 README 的部署说明"

::: tip 💡 commit message 规范 推荐用类型+描述的格式:

• feat: 新功能
• fix: 修复 bug
• docs: 文档更新
• style: 代码格式(不影响功能)
• refactor: 重构(不改变功能)
• test: 测试相关
• chore: 构建/工具相关

这样以后翻历史记录,一眼就知道每次提交做了什么。 :::

---

4. 平行宇宙:分支(Branch)的魔法

这是 Git 最强大的功能!

::: tip 🌌 用游戏理解分支 想象你在玩游戏,前面有个大 Boss(上线新功能),你怕打不过导致游戏结束(系统崩溃)。

这时候,你可以开一个分支(Branch),相当于复制了一个平行世界:

• 在平行世界(新分支)里打 Boss,输了也不怕,因为主世界(主分支)没影响
• 打赢了就把成果"合并"回主世界
• 多个队友可以在各自的平行世界开发,互不干扰 :::

4.1 主分支 vs 开发分支

分支类型	作用	特点
main/master	稳定的线上版本	只有测试通过的代码才能进来
dev/feature-xxx	你的试验田	这里炸了地球也没关系,不影响主分支
hotfix-xxx	紧急修复	生产出 bug 时,从 main 开分支快速修复

4.2 分支操作流程

创建分支并切换:

# 创建新分支
git branch feature-login

# 切换到新分支
git checkout feature-login

# 或者一步到位:创建并切换
git checkout -b feature-login

在分支上开发:

# 在 feature-login 分支上改代码...
git add .
git commit -m "feat: 添加登录表单"

合并回主分支:

# 切回主分支
git checkout main

# 合并 feature-login
git merge feature-login

# 删除已合并的分支(可选)
git branch -d feature-login

::: tip 💡 什么时候用分支? 个人开发:

• 要尝试新想法,不确定会不会搞崩现有代码 → 开分支
• 修一个复杂 bug,需要多次实验 → 开分支

团队开发:

• 每个功能一个分支,互不干扰
• 开发完提 Pull Request,队友 review 后再合并 :::

---

5. 常用命令速查表

命令	作用	人话解释	使用频率
git init	初始化	"在这里建个新仓库"	项目开始时用一次
git status	查看状态	"现在乱不乱?有没有东西没提交?"	⭐⭐⭐⭐⭐ 极高频
git add .	添加所有	"把桌上所有文件都扔进快递盒"	⭐⭐⭐⭐⭐ 每次提交前
git add file.txt	添加单个	"只要这个文件"	⭐⭐⭐⭐ 选择性添加
git commit -m "..."	提交	"封箱!贴上标签,写上这次改了啥"	⭐⭐⭐⭐⭐ 完成功能时
git log	查看历史	"翻翻以前的日记"	⭐⭐⭐ 回顾历史
git checkout -b dev	创建新分支	"我要去平行宇宙 dev 探险了"	⭐⭐⭐⭐ 开新功能
git checkout main	切换分支	"回地球(主分支)看看"	⭐⭐⭐⭐ 切换任务
git merge dev	合并分支	"把平行宇宙的成果带回地球"	⭐⭐⭐ 完成功能
git branch	查看分支	"现在有哪些平行世界?"	⭐⭐⭐ 查看状态
git branch -d feature	删除分支	"这个平行世界不需要了,删掉"	⭐⭐ 合并后清理
git push	推送	"把本地存档上传到云端"	⭐⭐⭐⭐⭐ 团队协作
git pull	拉取	"把云端最新存档下载到本地"	⭐⭐⭐⭐⭐ 团队协作

---

6. 进阶:解决冲突与远程协作

6.1 冲突(Conflict)是什么?

当你和队友同时修改了同一个文件的同一行代码,Git 就会懵:"我该听谁的?"这就是冲突(Conflict)。

6.2 怎么解决冲突?

Step 1:打开冲突文件,会看到这样的标记:

<<<<<<< HEAD
你的代码
=======
队友的代码
>>>>>>> feature-branch

Step 2:手动选择要保留的代码,或合并两者:

# 保留你的代码 → 删除队友的部分和标记
# 保留队友的 → 删除你的部分和标记
# 合并两者 → 综合两边的代码

Step 3:删除所有标记,保存文件

Step 4:重新提交

git add 解决冲突的文件
git commit  # Git 会自动生成合并提交

::: tip 💡 避免冲突的最佳实践

• 频繁沟通:队友改同一个文件前,先打个招呼
• 小步提交:不要攒着大量代码最后才提交,增加冲突概率
• 分支隔离:不同功能用不同分支,减少直接冲突
• 用 Pull Request:合并前让队友 review,提前发现问题 :::

6.3 远程仓库(Remote)

远程仓库(比如 GitHub/GitLab)就是云端的备份中心。

核心操作:

操作	命令	作用
关联远程	git remote add origin https://github.com/...	第一次连接云端
推送	git push -u origin main	把本地存档上传
拉取	git pull	把云端最新存档下载并合并
克隆	git clone https://github.com/...	复制整个仓库到本地

::: tip 💡 push 和 pull 的区别

• push:你的本地代码 → 云端(你改了东西,要同步给队友)
• pull:云端代码 → 你的本地(队友改了东西,你要同步下来)

最佳实践:每天开始工作前先git pull,下班前git push,这样减少冲突。 :::

---

7. 总结:Git 的核心思想

Git 不是简单的"版本备份",而是一个完整的代码协作系统:

特性	解决的问题	生活类比
版本管理	代码改错了怎么办?	时光机,随时回退
分支	多人同时改同一个文件怎么办?	平行宇宙,互不干扰
暂存区	这次提交不想包含所有修改怎么办?	快递盒,挑拣要寄的东西
远程协作	怎么和队友共享代码?	云备份,随时随地同步
冲突处理	真的改到同一行了怎么办?	智能合并 + 手动协调

学习建议:

1. 先用起来:不要等"完全理解"再用,一边用一边理解
2. 从简单开始:个人项目先掌握add/commit/push/pull,团队项目再学分支
3. 看 Git 图形化工具:SourceTree、GitHub Desktop 等,可视化帮助理解
4. 遇到问题不要慌:Git 的设计就是为了让你能安全地尝试,大不了git reset

---

附录:名词速查表

名词	英文	用人话解释
仓库	Repository	存放所有版本历史的数据库
提交	Commit	一次完整的版本记录,像存档点
分支	Branch	独立的开发线,像平行宇宙
合并	Merge	把一个分支的改动整合到另一个分支
冲突	Conflict	同一行代码被修改多次,Git 不知道选哪个
暂存	Stage	把修改加入"准备提交"的列表
远程	Remote	云端的仓库副本(GitHub/GitLab)
克隆	Clone	复制整个远程仓库到本地
推送	Push	本地 → 远程,上传代码
拉取	Pull	远程 → 本地,下载代码
检出	Checkout	切换到某个分支或版本
HEAD	-	当前所在的分支/版本的指针