终于到了要掌握 branch 这一步

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

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

总体思路

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

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。

单人 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，形成一个稳定版本
  • 注意：为每个功能或任务使用新的临时分支，完成后清理，以保持分支结构清晰可控。