第 3 章：分支管理——创造平行宇宙 (Branching)¶
🌌 平行宇宙和时间线——安全地探索新功能¶
在这一章，你会学到 Git 最强大的特性之一：分支（Branch）。分支让你可以在不影响成熟代码的前提下，安全地尝试新功能。
你会学到¶
✅ 什么是分支：理解"平行宇宙"模型，知道为什么分支如此安全
✅ 为什么需要分支：多人开发、实验新功能、修复Bug时为什么必须用分支
✅ 创建和切换分支：学会在不同"平行宇宙"之间切换
✅ 合并分支：将成熟的功能合并回主线，而不损坏已有的代码
✅ 分支命名规范：用专业的方式命名分支
3.1 什么是分支？¶
问题：多人同时开发同一个项目¶
想象你和队友 Alice、Bob 一起开发一个 Python Flask API：
🚀 主线（main 分支） 正在运行生产环境，用户正在使用
👤 你：想添加一个新数据库查询功能
👤 Alice：想优化 API 响应速度
👤 Bob：想修复一个登录 Bug
如果你们都直接改 main 分支的代码：
你: app.py 第 45 行改了 X
Alice: app.py 第 45 行改了 Y
Bob: app.py 第 45 行改了 Z
现在谁的改动生效？代码冲突！💥
最糟糕的是，如果 Alice 的改动有 Bug，一旦正式上线并触发，整个生产环境都会挂掉。
解决方案：分支（Branch）¶
名词解释：Branch
分支 = 一条独立的代码开发线。每条分支都是完整的项目副本，互不影响。
想象你在看一个树——main 分支是树干，其他分支是从树干长出来的树枝。
每条树枝上都有完整的项目代码，你可以在树枝上随便修改，不影响树干。
分支的超能力¶
使用分支，上面的场景变成了：
main 分支（生产环境）：稳定，用户正在使用 ✅
feature/database（你的分支）
├─ 代码随便改
├─ 可以删除、重构、试验
└─ 玩坏了也没关系
feature/performance（Alice 的分支）
├─ 优化代码
└─ 完全独立，不影响任何人
bugfix/login（Bob 的分支）
├─ 修复 Bug
└─ 修好了再合并回 main
每个人都在自己的分支上工作，互不干扰。等功能稳定后再合并回 main 分支。
为什么分支如此安全？¶
✅ 隔离：每条分支完全独立，一个分支的Bug不会影响其他分支或main分支
✅ 并行开发：多人可以同时在不同分支上工作
✅ 试验性：可以大胆尝试新功能，玩坏了删掉重来
✅ Code Review：合并前可以让队友审查代码（通过 Pull Request）
✅ 历史保留：分支被删除后，提交记录永远保存在 main 分支里
举个例子 / 类比理解
分支就像一个 平行宇宙小说：
🌍 主世界（main）：现实中正在发生的事
🌌 平行世界 1（feature/dragon）：假如世界上出现了龙会怎样？
🌌 平行世界 2（feature/magic）：假如人类有魔法会怎样？
在平行世界里你可以随便尝试，看看效果。如果你喜欢某个平行世界的情节，就把它合并回现实。否则，那个平行世界就永远关闭了，现实世界不受影响。
3.2 创建与切换分支¶
现在我们开始实操。
分支命名规范¶
在创建分支前，要知道怎样给分支起名。专业的分支名字让代码审查更容易。
推荐的命名模式：
feature/功能名 新功能分支（用 feature/ 前缀）
feature/user-auth
feature/database-query
feature/api-caching
bugfix/Bug名 修复 Bug 分支（用 bugfix/ 前缀）
bugfix/login-error
bugfix/api-timeout
refactor/说明 重构分支（用 refactor/ 前缀）
refactor/database-layer
refactor/error-handling
docs/说明 文档更新分支
docs/api-documentation
分支名命名要点：
- 使用英文（Git 历史记录主要是英文）（编者注：德日法西都可以，你自己看的明白就行）
- 用连字符 - 分隔单词（不要用下划线或空格）
- 名字要有意义（feature/fix 是模糊的，bugfix/login-validation 更清楚）
- 长度合理（一或两个单词就够）
步骤 1：创建一个新分支¶
你要开发一个新功能：添加用户认证。
方法 A：命令行
# 创建一个新分支，并立即切换到这个分支
# 分支名：feature/user-auth
git switch -c feature/user-auth
# 你会看到输出：
# Switched to a new branch 'feature/user-auth'
或者用更传统的语法也行（效果一样）：
git checkout -b feature/user-auth
方法 B：VSCode
打开 Source Control 面板
找到面板顶部显示当前分支名的地方（例如 main）
点击那个分支名
在弹出的菜单里选择 "Create new branch"
输入新分支名 feature/user-auth
按 Enter
步骤 2：确认你在正确的分支上¶
很重要：在提交代码前，确认你在正确的分支上。
方法 A：命令行
# 这个命令显示所有分支，当前分支会被标记为 *
git branch
# 输出类似：
# main
# * feature/user-auth
星号 * 表示你正在 feature/user-auth 分支上。
方法 B：VSCode
看左下角的状态栏。分支名会显示在那里（例如 feature/user-auth）。点击它可以快速切换分支。
步骤 3：在分支上进行开发¶
现在你可以安全地修改代码，不用担心影响 main 分支。
创建一个新文件 auth.py：
# auth.py - 用户认证功能
def verify_login(username, password):
"""
验证用户登录信息。
这是一个演示函数，实际项目中会连接数据库。
"""
# 这里应该连接数据库检查 username 和 password
print(f"验证用户: {username}")
return True
def generate_token(user_id):
"""生成一个会话 token（简化版）"""
return f"token-{user_id}"
步骤 4：提交改动¶
就像之前一样提交代码：
git add auth.py
git commit -m "feat: 添加用户认证模块"
或者用 VSCode 完成同样的操作。
重要
你现在的所有改动都在 feature/user-auth 分支上。main 分支完全不受影响。
如果你想看看 main 分支现在什么样，切换到 main，你会发现 auth.py 文件不存在。这就是分支的隔离性。
步骤 5：切换分支¶
想象现在 Bob 说："嘿，我发现了一个登录 Bug，需要立即修复。" 你需要暂停当前工作，帮他修 Bug。
方法 A：命令行
# 切换回 main 分支
git switch main
# 或者用跨平台的旧语法
git checkout main
# 输出：
# Switched to branch 'main'
现在你在 main 分支上，auth.py 文件消失了（因为它只存在于 feature/user-auth 分支）。
方法 B：VSCode
点击左下角的分支名 feature/user-auth → 选择 main → 完成。
重要警告
切换分支前，必须提交或存储 所有改动。否则 Git 会拒绝切换：
error: Your local changes to the following files would be overwritten by checkout:
some_file.py
Please commit your changes or stash them before you switch branches.
解决方法：
- ✅ 提交改动：git commit -am "message"
- ✅ 或者暂存：git stash（第 7 章详细讲）
3.3 合并分支（Merge）¶
现在 feature/user-auth 分支的代码已经完成并测试通过了。你需要把这些改动合并回 main 分支。
合并的原理¶
feature/user-auth 分支：
commit A
commit B
commit C（auth.py 功能完成）
｜
｜（合并）
v
main 分支：
commit 1
commit 2
commit C（auth.py 被添加到 main）
合并后，main 分支拥有了 feature/user-auth 的所有改动。
步骤 1：切换回 main 分支¶
git switch main
步骤 2：执行合并¶
方法 A：命令行
# 将 feature/user-auth 分支合并到当前分支（main）
git merge feature/user-auth
# 输出应该像这样：
# Updating abc123..def456
# Fast-forward
# auth.py | 15 ++++++++++++++
# 1 file changed, 15 insertions(+)
方法 B：VSCode
确保你已经切换到 main 分支
打开命令面板：Ctrl+Shift+P（Windows）或 Cmd+Shift+P（macOS）
输入 "Git: Merge Branch"
选择要合并的分支 feature/user-auth
完成！
步骤 3：验证合并成功¶
# 现在 main 分支拥有了 auth.py
git log --oneline
# 输出：
# def456 feat: 添加用户认证模块
# abc123 feat: 初始化项目
# ...
或者直接看文件系统，auth.py 应该已经出现在 main 分支的工作目录里。
步骤 4：删除已合并的分支（可选）¶
合并完成后，feature/user-auth 分支可以删除了。保留它会导致分支列表臃肿。
# 删除本地分支
git branch -d feature/user-auth
# 如果删除失败（比如分支没有完全合并），用强制删除
git branch -D feature/user-auth
或者用 VSCode：
1. 右键点击分支名
2. 选择 "Delete Branch"
提醒
删除本地分支后，提交历史仍然保留在 main 分支里。你可以随时查看 git log 看到曾经是谁提交的改动。
分支本身只是一个"指针"，删除分支不会删除提交。
冲突解决简介¶
有时候合并分支时，Git 会说："两个分支修改了同一个文件的同一行，我不知道应该用哪个。" 这叫 merge conflict（合并冲突）。
冲突示例：
# main 分支的 app.py 第 10 行：
<<<<<< HEAD
API_BASE_URL = "https://prod.api.com"
======
API_BASE_URL = "https://dev.api.com"
>>>>>> feature/user-auth
这说明主分支和功能分支在这一行有不同的改动。
解决方法（简化版）：
打开有冲突的文件
VSCode 会高亮显示冲突区域
点击 "Accept Current"（用主分支的）、"Accept Incoming"（用功能分支的）或 "Accept Both"（两个都要）
手动编辑到满意为止
git add 和 git commit 完成合并
（第 6 章会详细讲冲突解决）
3.4 分支最佳实践¶
1️⃣ 规则：每个功能用一个分支¶
❌ 错误：所有改动都在 main 分支上
✅ 正确：给每个功能创建一个分支（feature/auth、feature/payment 等）
2️⃣ 规则：分支要保持小而精¶
❌ 错误：feature/huge-refactor 包含 50 个文件的改动
✅ 正确：每个分支只完成一个明确的功能或修复
3️⃣ 规则：经常同步主分支¶
在开发途中，经常从 main 拉取最新代码，保持同步：
git fetch origin main
git merge origin/main
这样可以早发现冲突，而不是积累到最后。
4️⃣ 规则：不要在主分支上直接提交¶
❌ 错误：在 main 分支上随便改代码
✅ 正确：创建 feature 分支，开发完成后通过 Pull Request 审查，再合并
3.5 常见问题排查¶
问题 1：分支创建后，旧代码还在¶
症状：我创建了 feature/new-feature 分支，但 main 分支的所有文件都复制过来了。
原因：这是对的！分支是完整的项目副本。如果不是这样，分支就没有意义了。
验证：
git log --all --oneline --graph
这会显示分支图表，你会看到 feature/new-feature 和 main 分别有自己的提交线。
问题 2：我忘了在正确的分支上¶
症状：我改好了代码，才发现我在 main 分支上改的，不是 feature/ 分支上。
解决：
# 先 commit 你的改动
git commit -m "feat: 我本应在 feature 分支上的改动"
# 创建一个新分支指向这个 commit
git branch feature/intended-feature
# 然后把 main 分支回退（第 7 章详细讲）
git reset --soft HEAD~1
问题 3：我想查看另一个分支的代码¶
不需要切换分支。用差异查看：
# 查看两个分支的差异
git diff main feature/new-feature
# 查看特定文件的差异
git diff main feature/new-feature -- auth.py
📚 关键概念总结¶
命令
作用
git branch
列出所有分支
git switch -c <分支名>
创建新分支并切换
git switch <分支名>
切换到既有分支
git merge <分支名>
合并分支到当前分支
git branch -d <分支名>
删除分支
git log --graph
查看分支图表
🚀 下一步¶
完成本章后，你已经能够：
- ✅ 理解为什么需要分支
- ✅ 创建和管理多个开发分支
- ✅ 安全地并行开发
- ✅ 合并功能完整的代码回主线
下一章：走向云端。你会学到如何把本地的分支 "推送" 到 GitHub，与队友共享代码。