游戏团队 Git 主干开发实践
介绍
这是一个 Unity 游戏团队的 Git 规范。仓库里既有代码,也有场景、预制体、贴图、配置表这类不好合并的资源;参与者包括程序、策划、美术和 QA。人一多、资源一多,Git 的问题就不再是「命令记不住」,而是协作方式把冲突、丢提交、漏文件放大了。
下面是我们为什么采用主干开发,以及分支、合并、推送、钩子和工作区的硬性规则。正文偏重原理和规则;附录 A 是按 Fork 界面写的程序日常操作,附录 B 是策划、美术、QA 的最少步骤。
先说结论
- 主干只有
main。策划、美术、QA 直接在主干提交;程序需要独立提交序列时,才开短功能分支。 - 拉取只允许 rebase,禁止
pull产生合并提交;合入主干只允许「rebase 之后--no-ff」这一种合并形态。 main和releases/*禁止 force;功能分支只有负责人能--force-with-lease。- 功能分支以负责人命名、带日期、以天计;发布从
main切releases/<平台>/<版本>,只接受 cherry-pick。 - 工作区默认必须是干净的;Unity 资源必须带
.meta;缓存和产物不提交。 - 工具统一用 Fork;规则靠服务器钩子兜底,不靠自觉。
总原则
规避问题,而不是事后救火
这是总原则:优先把问题消灭在萌芽之中,而不是发生之后再处理。 从源头规避,比事后解决少一个数量级的工作量。
Git 相关的冲突、丢提交、漏文件、脏工作区,大多不是「技术很难」,而是「允许它发生」。允许子目录单独提交,就会漏文件;允许 pull 默认 merge,历史就会变成蜘蛛网;允许功能分支活两周,冲突就会从几行变成几百行。
规则的价值不在于出事后有人会修,而在于让这类事尽量不要发生。出了 force 主干、改写已上主干的历史这类事,停手找人,不要自己补救。
简单比复杂好
奥卡姆剃刀:如无必要,勿增实体。Git 历史一条直线,比一张蜘蛛网好。直线只要顺着看;蜘蛛网是有向无环图,阅读、向别人解释、用二分法查问题时,心智负担都会陡增。
没有合并提交时,历史是一条线:
|
|
多次用 merge 拉取之后,历史变成 DAG:
|
|
后者每一个合并节点都有两个父提交。人眼难以判断「真正的主干」在哪;git bisect 也会在分叉上来回跳,定位回归的成本明显高于直线历史。
这套流程用规则换简单:少分支、短分支、pull 只 rebase、合入主干只允许一种合并形态。多记几条约束,换来日常几乎不用分析 Git 图。
心智负担
规则换来的不是「Git 知识更多」,而是日常更少要想:
- 打开历史,顺着一条线看下去就行,不必分析双亲提交;
- 普通人用
Ctrl+Shift+A只看当前分支,不必面对全部分支标签; - 策划、美术、QA 只在主干上提交、拉取、推送,不必建分支。
反例是 GitFlow:长期 develop、再加若干长期发布线,功能分支还要在它们之间来回合并。线一多,人就要先问「我现在在哪条线上、该合到哪」。我们不采用那套。发布需要冻结时,临时从主干切 releases/...,用拣选进内容,而不是再养一条长期开发分支。
角色与流向
主干分支名是 main。
|
|
- 策划 / 美术 / QA:只在
main上工作,不要自己新建分支。步骤见附录 B。 - 程序:需要独立提交序列、或暂时不能进主干时,走短功能分支。分支由一个人负责,可以多人共用。合入主干由负责人做。步骤见附录 A。
- 发布负责人:从
main切releases/<平台>/<版本>,之后只用拣选(cherry-pick)把已在主干上的提交送进发布分支。
这套流程没有 PR 环节。合入主干是负责人在本地做完 --no-ff 合并后推 main。
尽早集成
任何功能做完之后都要放到主干里。真正的问题往往出现在合并之后:接口对不上、资源互相覆盖、语义已经漂移。减少这些问题的办法是尽早集成,而不是把分支留到「完全做完」。
从源头减少冲突
冲突发生后再解,是在解决问题;任务分配时不要有交集,是在规避问题。同一张表、同一个预制体、同一场景不要同时派给两个人。即便仍有冲突,范围也会很小,当天就能找相关人处理。
分支活得越久,风险越大
分支存在越久:
- 与主干的差异越大,冲突越多;
- 反馈越晚,错误越晚被发现;
- 相关人可能已经忘掉当时为什么那样改,语义偏差更难处理。
功能分支应当短命,以天计,不要以周计。
何时上主干,何时开分支
| 情况 | 走哪条线 |
|---|---|
| 资源、表、文案、小修复,提交后别人打开工程仍能玩 | 直接在 main |
| 需要一组独立提交、或暂时不能让别人用到这些改动 | 短功能分支,rebase 同步 main |
| 半成品会破坏「打开就能玩」 | 必须走短功能分支,不要推进 main |
如果仓库没有功能开关框架,就不要把「未完成功能靠开关关掉」当成进主干的理由。开关不存在,半成品进了主干,别人打开工程就会坏。
两种尽早集成的方式:
- 直接在主干上开发。策划、美术、QA 默认走这条路。
- 新建短生命周期功能分支,用同步(rebase)尽早与主干集成。
主干开发
这套流程采用主干开发(Trunk Based Development):全员协同在同一条主干上,抵制长生命周期开发分支。
- Trunk Based Development: Introduction
- Software Engineering at Google 第 16 章 Version Control and Branch Management
- Google 主干开发与版本控制实践
合并提交
定义
合并提交指有两个或多个父提交的提交。来源有两类:
pull默认的 merge 策略产生的提交;- 主动把一个分支 merge 进另一个分支产生的提交。
快进(fast-forward)不是合并提交:指针直接前移,不产生新节点。非快进(--no-ff)即使可以快进,也强制创建一个合并提交。
缺点
- 合并提交和普通提交一样会引入改动。 功能分支经常已经与主干差得很远,合并时一次误操作(选错「采用哪一侧」、错误地解决冲突)可能丢掉主干上的改动。
- 丢掉一侧之后,默认日志看不出来。
git log默认沿第一父提交走。如果合并时完全丢弃主干一侧,主干上那一串提交不会出现在默认日志里,容易误判「主干没丢东西」。 - 历史变成蜘蛛网。 没有合并提交时,历史是一条直线;有了来自 pull merge 的合并提交,历史变成有向无环图。阅读麻烦,
git bisect也更难用。
因此:日常禁止 pull 产生合并提交。拉取必须 rebase。
这类问题在 Git 合并提交的问题 里有更细的展开。
优点
功能分支合入主干时,仍然需要一次合并提交:它记下何时、由谁把这组改动并入主干。没有这个节点,后来说不清「这批功能是哪天进主干的」。
唯一允许的合并形态
为了既留下合入记录、又不丢主干,这次合并必须同时满足:
- 合入前功能分支已经 rebase 到主干最新提交;
- 使用非快进(
--no-ff)合并,即使只有一个提交也不允许快进。
|
|
约束:
- 合并提交的第一父提交必须是主干当前提交,也就是功能分支最早那笔提交的父提交。rebase 之后,这条线上没有任何「主干有、功能分支没有」的提交,因此不可能丢掉主干。
- 合并提交的第二父提交必须是功能分支的最后提交。
这与「两侧都有独有提交」的分叉合并不是一回事。后者会织出蜘蛛网,服务器钩子要拒绝;前者只是在已经直线化的历史上打一个合入标记。
禁止的合入方式
pull产生的 merge(忘了勾选 rebase)- squash 合入主干(丢掉功能分支上的提交序列,也失去可核对的合入形态)
- 把发布分支 merge 回
main(发布线上的拣选历史会缠进主干) - 把功能分支直接 merge 进发布分支(发布只接受拣选)
推送与 force
main与releases/*禁止 force。 这两条线的历史只能往前走。- 功能分支 rebase 到主干之后,远程分支还停在旧提交上,需要
--force-with-lease才能推上去。这件事只由该分支负责人做。 其他人不要 force 这条分支。 - 命名空间用负责人姓名,不表示禁止别人往这条分支推送。共用者正常 push;负责人同步之后,其他人先拉再继续改,避免各 rebase 各 force,把别人的提交冲掉。
- 永远不要 force 别人负责的分支,除非负责人明确让你代做同步。
软件选择:统一 Fork
候选过 SourceTree、TortoiseGit。最终统一用 Fork。所有人用同一款客户端,才能互相指导,培训成本最低。
为什么不是另外两款
| 客户端 | 出局原因 |
|---|---|
| SourceTree | 体量较大的 Unity 仓库里操作卡顿,日常不可用 |
| TortoiseGit | 可以在某一个目录里提交。看起来方便,实际会漏提交其他目录的文件。应该从源头避免漏提交,而不是事后对清单 |
Fork 始终展示整个工作区的文件改动,提交时不容易漏文件。
Pull 时自动暂存
Fork 支持在 pull 时自动 stash 未提交的内容,pull 完成后再 stash pop。拉取前后工作区一致,不必先手动把改动藏起来。第一次 pull 时勾选 Stash and reapply local changes,并同时勾选 Rebase instead of merge。
Lean Branching(程序用功能分支时)
Fork 的 Lean Branching 就是「尽早集成」的具体操作:
- 功能分支由负责人用 rebase 同步主干。尽量频繁,最少每天一次。当天的冲突可以立刻找相关人,记忆还清楚;拖到两三周后再解,相关人可能已经忘掉。共用者不要自己 rebase 主干再 force。
- 同步完成后,由负责人用非快进合并到主干,保留何时并入主干的记录。
Fork 的 Finish 在「功能分支只有一个提交」时会快进。这套流程不允许快进合入主干。 应使用 Merge,并创建合并提交(--no-ff),不要用会快进的 Finish。
- ⭐️ Lean Branching - a git branching model to keep clean history · Issue #1432 · fork-dev/TrackerWin
- 站内旧文:Git 精干分支
其他与原则对齐的能力
- Issue 链接:提交说明里的
Task ID/Bug ID可配置成一键跳转任务系统(TAPD、Jira 等)。具体链接由仓库维护者在 Fork 的仓库设置里配置,因团队而异。 - 整库工作区:始终能看到所有文件改动,而不是某个子目录。
- 性能:体量较大的 Unity 仓库里操作流畅。
- Discard 不区分文件种类:撤销改动时,不必自己判断「新增文件要删」还是「已修改文件要 checkout」。一个是文件系统操作,一个是 Git 操作,Fork 合成同一个「丢弃」。
- 快速过滤器:
Ctrl+Shift+A只显示当前分支。普通人只关心主干历史,不必面对全部分支标签。 - Amend:未推送的提交可用勾选框快速增补,不必再学
commit --amend。已推送的提交不要 Amend。 - 改动文件视图:支持树状、列表、文件名,按需切换。
服务器钩子
规则写在文档里,挡不住误操作。钩子放在服务器上,不用每个人安装,能从源头禁止出问题。
下面只给判断规则,脚本实现可以用 Git 服务器的 pre-receive 钩子。本地钩子(例如只检查 Unity .meta 是否与资源成对,见 Unity 提交时检查 meta 文件)和服务器钩子不是一回事,不要混用。实现思路可参考 Git 干净的历史 和 git-check-useless-merge。
拒绝分叉合并,允许 rebase 后的 --no-ff
对即将进入 main 的每个新提交,按下面判断(人也可以用同一套话检查):
- 若该提交只有一个父提交:放过(普通提交或快进,快进合入主干仍应由流程避免,见「合并提交」)。
- 若该提交有两个父提交:设第一父提交为 P1,第二父提交为 P2。
- 若 P2 的历史已经包含 P1(也就是 rebase 之后的
--no-ff):允许。 - 若 P1 与 P2 各自都有对方没有的提交(两侧都有独有提交):拒绝。这就是分叉合并,典型来源是忘了勾选 rebase 的
pullmerge。
- 若 P2 的历史已经包含 P1(也就是 rebase 之后的
- 有两个以上父提交:拒绝。
不要把这条理解成「禁止所有非快进」。禁止的是分叉,不是合入标记。
Issue 格式检测
普通提交说明必须以 Task ID 或 Bug ID 开头,后接数字和空格,再写做了什么:
|
|
判断句:第一行匹配 ^(Task|Bug) ID[0-9]+ (注意 ID 与数字之间无空格,数字后必须有空格)。--no-ff 合入主干的合并提交可以使用 Merge branch '...',不必再带 Issue:Issue 已经写在功能提交里。
分支规范
新建功能分支必须同时满足:
- 以负责人姓名全拼作为命名空间,例如张三
zhangsan; - 带上建立分支的日期,例如
20261029; - 用英文简短说明分支功能,例如
startup-time-optimization; - 日期与功能说明之间用
-分隔。
最终示例:
|
|
命名空间是负责人,不是「仅此人可推」。一条分支由一个人负责,可以多人共用:其他人可以在这条分支上提交和推送;rebase、force-with-lease、合入主干只由负责人做。
功能分支合入主干并确认无误后应删除,避免仓库里堆积长期分支。
发布分支流程
确定发布版本时,从 main 新建分支,以 releases 开头,加上平台与版本,用 / 分隔:
|
|
建立发布分支之后:
- 所有进入该发布版本的内容必须用拣选(cherry-pick)提交到发布分支;
- 不要把功能分支直接 merge 进发布分支;
- 不要把发布分支 merge 回
main。发布上发现的问题先在main修好,再拣选到发布分支; - 发布分支禁止 rebase、禁止 force。
热更在打出热更包的那次提交上加 Tag,四段式,例如 releases/android/1.1.0.1(第几次热更就写几)。整包存档、热更 Tag 的配套步骤按团队流程执行,不在本文展开。
工作区规范
- 工作区默认必须是干净的(Clean)。 用 Unity 打开工程后,不能有任何不相关的文件改动,而且能直接进入游戏。开发人员必须始终保持这个状态;不干净时立即清理,避免把本地垃圾扩散成别人的问题。
- 不需要纳入版本控制的文件用
.gitignore忽略。 如果只是自己本地的文件,用.git/info/exclude,不要把个人忽略规则写进仓库的.gitignore。引擎缓存和打包产物(如Library/、Temp/、Logs/和打包输出目录)已经在.gitignore里,不要提交。 - 理论上,所有出现在工作区、又不该被忽略的文件都需要提交。 看见却不提交,等于给别人留地雷。Unity 资源改动必须连同对应
.meta一起提交;如果团队装了本地.meta检查钩子,漏了会被拦住,实现思路见 Unity 提交时检查 meta 文件。 - 不要改
.gitattributes去转换.asset的换行。.asset可能是文本也可能是二进制,乱转行尾会把整个文件变成一次无意义 diff。相关背景见 Git 自动转换文件换行符。
附录 A:程序日常操作
按 Fork 界面写步骤,命令只作对照。为什么这样,见正文「合并提交」和「推送与 force」。
第一次
- 安装 Fork。姓名用中文全名,邮箱用工作邮箱。
- 第一次 Pull 勾选并保持:
Rebase instead of mergeStash and reapply local changes
- 如果团队装了
.meta检查钩子,按仓库说明安装。它只检查 Unity 资源与.meta是否成对,不是服务器钩子;实现思路见 Unity 提交时检查 meta 文件。 Ctrl+Shift+A:历史只显示当前分支,日常更干净。- 任务单跳转:由仓库维护者在 Fork 里配置
Task ID/Bug ID的链接模式,指向 TAPD、Jira 等任务系统。
主干日常
小修复、表、资源、不会破坏「打开就能玩」的改动,直接在 main 上做,流程与策划相同:提交 → Ctrl+Pull → Ctrl+Push。
提交说明第一行:
|
|
工作区不干净时不要 rebase、不要切分支去合入。先提交、丢弃或 stash,让左边文件列表空掉。
功能分支生命周期
一条分支由一个人负责,可以多人共用。命名空间是负责人,不是「仅此人可推」。
| 谁 | 可以做 | 不要做 |
|---|---|---|
| 负责人 | 建分支、每天 rebase 同步 main、force-with-lease、--no-ff 合入、删除分支 |
force main |
| 共用者 | 在该分支上提交并推送;负责人同步之后再拉再改 | 自己 rebase 主干再 force 这条分支 |
从最新 main 建分支
- 先切到
main,Ctrl+Pull,确认已在最新主干。 - 新建分支,名称:
|
|
例如:zhangsan/20261029-startup-time-optimization。
对照:git checkout main && git pull --rebase && git checkout -b zhangsan/20261029-startup-time-optimization
日常提交
与主干相同的 Issue 前缀。改 Unity 资源必须带上 .meta。看整个工作区,不要只提交某一个目录。
共用者直接在该分支上 commit、push。推之前先 Pull(rebase)。
负责人:每天同步主干
最少每天一次。冲突当天找改同一文件的人,记忆还清楚。
- 工作区干净。
- 大规模改脚本前退出 Unity Play。
- 把当前功能分支 rebase 到最新
main(Fork 的 Rebase 或 Lean Branching 的 Sync)。 - 只有负责人在 rebase 之后对该远程功能分支 force-with-lease。
- 同步完成后通知共用者:先 Pull,再继续改。
对照:git fetch origin && git rebase origin/main && git push --force-with-lease
永远不要 force main,也不要 force releases/*。
Fork 的 Lean Branching Finish 在「只有一个提交」时会快进。这套流程不用 Finish 合入主干。
冲突
rebase 或 stash pop 出现冲突:
- 当天找改同一文件的人一起看;
- 预制体、场景、配置表目录不要盲目选「采用我的 / 采用他们的」;
- 解完后继续 rebase,不要半路改用 merge 把主干拉进来。
负责人:合入主干
- 功能分支已 rebase 到最新
main,工作区干净。 - 切到
main,Ctrl+Pull。 - Merge 功能分支,创建合并提交(
--no-ff)。即使功能分支只有一个提交,也不允许快进。 - 推
main(普通 Push,不是 force)。 - 删除本地和远程功能分支。
对照:
|
|
不要 squash 合入主干。合并提交说明可以用 Merge branch 'zhangsan/20261029-startup-time-optimization',Issue 已经写在功能提交里。
发布
- 从最新
main切发布分支:
|
|
- 之后进入该版本的内容只做拣选(cherry-pick),不要把功能分支 merge 进发布分支。
- 发布分支禁止 rebase、禁止 force。
- 发布上发现的问题:先在
main修并推上去,再把那次提交拣选到发布分支。不要在发布分支上开新功能,也不要把发布分支 merge 回main。 - 热更 Tag 四段式,例如
releases/android/1.1.0.1。整包存档按团队流程执行。
Fork:在 main 上找到要进发布的提交 → Cherry-pick 到当前检出的发布分支 → 普通 Push。
Unity 注意
- 大规模 rebase 前:工作区干净,退出 Play。脚本正在编译时不要切分支。
- 漏
.meta会被本地检查钩子拦住;被拦就补上对应 meta,不要--no-verify。 - 预制体 / 场景 / 配置表冲突:找改同一份资源的人,不要单方面选一侧。
- 改文件名大小写:先改成临时名提交,再改回正确大小写提交,
.meta一起改。见附录 B。 - 不要改
.gitattributes去转换.asset换行。.asset可能是文本也可能是二进制。 Library/、Temp/、Logs/和打包输出目录已在.gitignore,不要强制添加。
停手清单
出现下面情况,停手找人。文档不教补救步骤(符合「规避而不是救火」):
- 已经 force 了
main或releases/* - 在发布分支上开了新功能,而主干没有
- 把发布分支 merge 回了
main - 对已经推上主干的提交做 interactive rebase / Amend
- 自己做历史重写(filter-branch、filter-repo 等)
- rebase 做到一半,历史既不是功能分支也不是主干
日常禁止、但还没铸成大错时自己停下来即可:
- 用 Fork Finish 快进合入主干
- squash 合入主干
- 共用者自己 rebase 主干再 force 功能分支
- 工作区不干净时 rebase
附录 B:策划 / 美术 / QA 最少步骤
只讲日常要用的最少步骤。默认只在主干
main上工作,不要自己新建分支。遇到冲突、合错、推送失败,找程序处理。
- 第一次:安装 Fork;姓名必须用中文全名,邮箱用工作邮箱;让程序给你仓库地址,用 Fork 打开,不要自己用命令行克隆;第一次 Pull 勾选
Rebase instead of merge和Stash and reapply local changes,之后保持。 - 提交:看整个工作区,勾选要提交的文件;改了 Unity 资源,对应的
.meta一起勾上;提交说明第一行按Task ID1000001 调整新手引导文案/Bug ID1000002 修正图标偏移的格式写;点 Commit。 - 拉取和推送:先
Ctrl+Pull,再Ctrl+Push;有未提交的本地改动也可以 Pull,Fork 会先藏起来再放回来;Push 被拒先Ctrl+Pull,仍失败就停手找程序,不要点 Force。 - 工作区必须干净:左边文件列表没有改动就是干净;用 Unity 打开工程后不能有不相关的改动,而且必须能直接进游戏;不干净立刻清理;误改的文件用 Fork 的 Discard 丢弃,不确定找程序。
- 弹出冲突:不要点「采用我的 / 采用他们的」,不要自己改冲突标记,停手找程序。
- 修改文件名大小写:Windows 不区分大小写,直接把
Icon.png改成icon.png,Git 经常当没改过。先改成临时名(如icon_tmp.png)提交一次,再改回正确大小写提交一次;.meta文件名也要一起改、一起提交。 - 不要做这些:不要自己新建分支;不要用 SourceTree、TortoiseGit;不要在某个子目录里单独提交;不要取消
Rebase instead of merge;不要长期留着脏工作区;不要 Force Push;冲突时不要自己选「采用我的 / 采用他们的」。 - 做完自己的改动:提交 →
Ctrl+Pull→Ctrl+Push;做完应能直接进游戏。
版权声明:
作者:dingding
链接:https://www.techfm.club/p/239372.html
来源:TechFM
文章版权归作者所有,未经允许请勿转载。

共有 0 条评论