终于到了要掌握 branch 这一步

Posted on Edited on In , Symbols count in article: 2.5k Reading time ≈ 2 mins.
基础的 git 已经完全掌握 (真的吗？)，现在来学习一下用 branch 管理代码吧！

搭 Mastodon 就开始偷别人的 branch 用，现在终于到了想试试用 branch 管理代码的这天。
因为代码是我的 Thesis 相关分析，所以维护人只有我一个，并没有真的让 branch 发挥最大作用。但就这样吧，以后有多人协作的时候再水一篇。

git 基础操作见：到底多少次才能学会使用 git

总体思路

在库中的代码应该有如下简单结构： 

1
2
3
4
5
6
7
repository/
├── main         # 主分支，存储稳定、可复现的分析流程与结果
│
├── development  # 开发分支，用于功能的集成与测试，准备合并进 main
│
└── daily-dev    # 日常维护分支，进行日常更新、调试与实验性修改

main 分支

代码的稳定版本
仅用于存储经过验证的、稳定的分析流程和结果。
所有面向他人共享或写论文前的代码版本，均以 main 为准。
合并到 main 前，代码应先通过 development 分支验证。

development 分支

开发版本
用于集成 daily-dev 的更新或功能模块，做阶段性整合和测试。
可以多人协作，完成后合并进 main。
较 daily-dev 更稳定，但仍可能频繁更新。

daily-dev 分支

日常维护
用于日常开发和维护，比如 bug 修复、分析修改、新图测试等。
自由度最高，适合个人工作。
重要变更建议定期合并进 development。

Tag（标签）的作用

用于记录关键的版本节点，方便快速回溯。
常用于标记：

  • 某次分析的正式版本（如 v0.2.1-analysis）
  • 提交给导师或合作作者的版本
  • 某个数据/包版本对应的代码快照

初始化和初次 push

在 GitHub 创建一个要存代码的空库，然后在本地执行如下操作： 

1
2
3
4
5
6
git init
git add .
git commit -m "Initial commit"
git branch -M main
git remote add origin <your-repo-url>
git push -u origin main

这里的操作和基本使用一样。还可以进一步使用 tag： 

1
2
git tag stable-0.0.1
git push origin stable-0.0.1

标记这一份代码是一份能跑通的稳定代码。

分支

基于某个分支创建新分支

创建新的开发分支： 

1
git checkout -b development

这个新的分支会默认基于当前分支，如果需要基于某个分支，可以先切过去，比如基于 main 的话： 

1
2
3
4
git branch                    # 查看当前处于哪个分支
git checkout main             # 切换到 main
git pull origin main          # 更新为最新版本（很重要）
git checkout -b development

或直接指定分支： 

1
git checkout -b development main

创建分支后推送到远程库： 

1
git push -u origin development

-u 表示将本地分支和远程分支绑定，之后只需用 git push 就可以自动推送到对应远程分支。

使用同样的办法来创建日常开发所用的分支，但记得检查想要基于哪个分支。日常开发一般基于 development： 

1
git checkout -b daily-dev development

日常操作都在 daily-dev 上进行，包括代码实验、小修改、调试。稳定后可通过如下方式合并到 development： 

1
2
git checkout development
git merge daily-dev

然后 git push 推送更新后的 development。

创建空白分支

有时候会需要一个相对干净的分支，因此需要创建 “空白” 的分支。
首先确认要添加到这个新空白分支的内容是否已经在当前的分支存在，但处于 unstaged 或 untracked 的状态。如果有，首先要备份这些文件。可以先挪到其它文件夹，之后再移回来。
如果有一些需要在当前分支 commit 的文件或更新，先执行对当前分支的操作。
完成上述检查之后，创建一个不含任何已有 commit 历史的分支，所以要用： 

1
git switch --orphan new-branch-name

然后把之前想要存在这个分支的所有文件搬回来，正常执行 git add 添加文件和后续的 git commit、git push 等操作。

删除分支

以删除 del-branch 为例。
如果仍然在需要删除的分支上，先切换到其它分支。如果不在这个分支上，比如在 main 或 develop，可以直接删： 

1
git branch -d del-branch

强制删除： 

1
git branch -D del-branch

即使没有合并过也会强制删除，谨慎使用。
然后删除远程分支： 

1
git push origin --delete old-feature

单人 vs 多人

如果是单人开发，目前的步骤已经够用。日常用 daily-dev，某些部分稳定之后可以适时合并到 development，代码全部稳定之后就合并到 main。不需要频繁重建分支，只要保持分支更新同步。即：

  • 日常开发全部在 daily-dev 分支进行
  • 某个功能或分析稳定之后，可以合并到 development 分支
  • 整体代码成熟、分析结果稳定时，再将 development 合并进 main，用于归档发布
  • 注意：不需要频繁重建分支，只要注意分支间保持同步更新，避免长时间分支内容差异太大

如果是多人开发，日常维护的分支可能需要频繁基于最新的 development 重建，再以最新代码为基础做修改。具体如下：

  • 所有人都从最新的 development 分支拉取一个自己的功能分支（例如 feature-x, fix-y, userA-dev 等），基于该分支进行开发
  • 每次开发前务必同步更新 development 分支，确保基于最新代码。如果已有分支落后较多，应基于最新的 development 重建分支
  • 开发完成后发起 Pull Request（PR）合并回 development，进行代码审查、测试等
  • 当多个功能合并并验证无误后，再由维护者将 development 合并到 main，形成一个稳定版本
  • 注意：为每个功能或任务使用新的临时分支，完成后清理，以保持分支结构清晰可控。