游戏团队 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 历史一条直线,比一张蜘蛛网好。直线只要顺着看;蜘蛛网是有向无环图,阅读、向别人解释、用二分法查问题时,心智负担都会陡增。

没有合并提交时,历史是一条线:

1 2 3 4 5 6 
gitGraph commit id: "A" commit id: "B" commit id: "C" commit id: "D" commit id: "E" 

多次用 merge 拉取之后,历史变成 DAG:

 1  2  3  4  5  6  7  8  9 10 11 12 13 14 15 16 17 18 19 
gitGraph commit id: "A" commit id: "B" branch localWork checkout localWork commit id: "L1" checkout main commit id: "T1" checkout localWork merge main id: "M1" checkout main commit id: "T2" checkout localWork commit id: "L2" merge main id: "M2" checkout main commit id: "T3" checkout localWork merge main id: "M3" 

后者每一个合并节点都有两个父提交。人眼难以判断「真正的主干」在哪;git bisect 也会在分叉上来回跳,定位回归的成本明显高于直线历史。

这套流程用规则换简单:少分支、短分支、pull 只 rebase、合入主干只允许一种合并形态。多记几条约束,换来日常几乎不用分析 Git 图。

心智负担

规则换来的不是「Git 知识更多」,而是日常更少要想:

  • 打开历史,顺着一条线看下去就行,不必分析双亲提交;
  • 普通人用 Ctrl+Shift+A 只看当前分支,不必面对全部分支标签;
  • 策划、美术、QA 只在主干上提交、拉取、推送,不必建分支。

反例是 GitFlow:长期 develop、再加若干长期发布线,功能分支还要在它们之间来回合并。线一多,人就要先问「我现在在哪条线上、该合到哪」。我们不采用那套。发布需要冻结时,临时从主干切 releases/...,用拣选进内容,而不是再养一条长期开发分支。

角色与流向

主干分支名是 main。

1 2 3 4 5 6 7 
flowchart LR nonDev[策划美术QA] -->|直接提交| trunk[main] dev[程序] -->|短功能分支 rebase| feature[name/date-topic] feature -->|no-ff合入| trunk trunk -->|切发布| release[releases/platform/version] trunk -->|修bug| trunk trunk -->|cherry-pick| release 

  • 策划 / 美术 / QA:只在 main 上工作,不要自己新建分支。步骤见附录 B。
  • 程序:需要独立提交序列、或暂时不能进主干时,走短功能分支。分支由一个人负责,可以多人共用。合入主干由负责人做。步骤见附录 A。
  • 发布负责人:从 main 切 releases/<平台>/<版本>,之后只用拣选(cherry-pick)把已在主干上的提交送进发布分支。

这套流程没有 PR 环节。合入主干是负责人在本地做完 --no-ff 合并后推 main。

尽早集成

任何功能做完之后都要放到主干里。真正的问题往往出现在合并之后:接口对不上、资源互相覆盖、语义已经漂移。减少这些问题的办法是尽早集成,而不是把分支留到「完全做完」。

从源头减少冲突

冲突发生后再解,是在解决问题;任务分配时不要有交集,是在规避问题。同一张表、同一个预制体、同一场景不要同时派给两个人。即便仍有冲突,范围也会很小,当天就能找相关人处理。

分支活得越久,风险越大

分支存在越久:

  • 与主干的差异越大,冲突越多;
  • 反馈越晚,错误越晚被发现;
  • 相关人可能已经忘掉当时为什么那样改,语义偏差更难处理。

功能分支应当短命,以天计,不要以周计。

何时上主干,何时开分支

情况 走哪条线
资源、表、文案、小修复,提交后别人打开工程仍能玩 直接在 main
需要一组独立提交、或暂时不能让别人用到这些改动 短功能分支,rebase 同步 main
半成品会破坏「打开就能玩」 必须走短功能分支,不要推进 main

如果仓库没有功能开关框架,就不要把「未完成功能靠开关关掉」当成进主干的理由。开关不存在,半成品进了主干,别人打开工程就会坏。

两种尽早集成的方式:

  1. 直接在主干上开发。策划、美术、QA 默认走这条路。
  2. 新建短生命周期功能分支,用同步(rebase)尽早与主干集成。

主干开发

这套流程采用主干开发(Trunk Based Development):全员协同在同一条主干上,抵制长生命周期开发分支。

合并提交

定义

合并提交指有两个或多个父提交的提交。来源有两类:

  • pull 默认的 merge 策略产生的提交;
  • 主动把一个分支 merge 进另一个分支产生的提交。

快进(fast-forward)不是合并提交:指针直接前移,不产生新节点。非快进(--no-ff)即使可以快进,也强制创建一个合并提交。

缺点

  1. 合并提交和普通提交一样会引入改动。 功能分支经常已经与主干差得很远,合并时一次误操作(选错「采用哪一侧」、错误地解决冲突)可能丢掉主干上的改动。
  2. 丢掉一侧之后,默认日志看不出来。 git log 默认沿第一父提交走。如果合并时完全丢弃主干一侧,主干上那一串提交不会出现在默认日志里,容易误判「主干没丢东西」。
  3. 历史变成蜘蛛网。 没有合并提交时,历史是一条直线;有了来自 pull merge 的合并提交,历史变成有向无环图。阅读麻烦,git bisect 也更难用。

因此:日常禁止 pull 产生合并提交。拉取必须 rebase。

这类问题在 Git 合并提交的问题 里有更细的展开。

优点

功能分支合入主干时,仍然需要一次合并提交:它记下何时、由谁把这组改动并入主干。没有这个节点,后来说不清「这批功能是哪天进主干的」。

唯一允许的合并形态

为了既留下合入记录、又不丢主干,这次合并必须同时满足:

  1. 合入前功能分支已经 rebase 到主干最新提交;
  2. 使用非快进(--no-ff)合并,即使只有一个提交也不允许快进。
 1  2  3  4  5  6  7  8  9 10 
gitGraph commit id: "A" commit id: "B" commit id: "C" branch feature checkout feature commit id: "D" commit id: "E" checkout main merge feature id: "M" 

约束:

  • 合并提交的第一父提交必须是主干当前提交,也就是功能分支最早那笔提交的父提交。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 就是「尽早集成」的具体操作:

  1. 功能分支由负责人用 rebase 同步主干。尽量频繁,最少每天一次。当天的冲突可以立刻找相关人,记忆还清楚;拖到两三周后再解,相关人可能已经忘掉。共用者不要自己 rebase 主干再 force。
  2. 同步完成后,由负责人用非快进合并到主干,保留何时并入主干的记录。

Fork 的 Finish 在「功能分支只有一个提交」时会快进。这套流程不允许快进合入主干。 应使用 Merge,并创建合并提交(--no-ff),不要用会快进的 Finish。

其他与原则对齐的能力

  • 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 的每个新提交,按下面判断(人也可以用同一套话检查):

  1. 若该提交只有一个父提交:放过(普通提交或快进,快进合入主干仍应由流程避免,见「合并提交」)。
  2. 若该提交有两个父提交:设第一父提交为 P1,第二父提交为 P2。
    • 若 P2 的历史已经包含 P1(也就是 rebase 之后的 --no-ff):允许。
    • 若 P1 与 P2 各自都有对方没有的提交(两侧都有独有提交):拒绝。这就是分叉合并,典型来源是忘了勾选 rebase 的 pull merge。
  3. 有两个以上父提交:拒绝。

不要把这条理解成「禁止所有非快进」。禁止的是分叉,不是合入标记。

Issue 格式检测

普通提交说明必须以 Task ID 或 Bug ID 开头,后接数字和空格,再写做了什么:

1 2 
Task ID1000001 修复登录卡死 Bug ID1000002 修正图标偏移 

判断句:第一行匹配 ^(Task|Bug) ID[0-9]+ (注意 ID 与数字之间无空格,数字后必须有空格)。--no-ff 合入主干的合并提交可以使用 Merge branch '...',不必再带 Issue:Issue 已经写在功能提交里。

分支规范

新建功能分支必须同时满足:

  1. 以负责人姓名全拼作为命名空间,例如张三 zhangsan;
  2. 带上建立分支的日期,例如 20261029;
  3. 用英文简短说明分支功能,例如 startup-time-optimization;
  4. 日期与功能说明之间用 - 分隔。

最终示例:

1 
zhangsan/20261029-startup-time-optimization 

命名空间是负责人,不是「仅此人可推」。一条分支由一个人负责,可以多人共用:其他人可以在这条分支上提交和推送;rebase、force-with-lease、合入主干只由负责人做。

功能分支合入主干并确认无误后应删除,避免仓库里堆积长期分支。

发布分支流程

确定发布版本时,从 main 新建分支,以 releases 开头,加上平台与版本,用 / 分隔:

1 2 
releases/android/1.4.0 releases/ios/1.4.0 

建立发布分支之后:

  • 所有进入该发布版本的内容必须用拣选(cherry-pick)提交到发布分支;
  • 不要把功能分支直接 merge 进发布分支;
  • 不要把发布分支 merge 回 main。发布上发现的问题先在 main 修好,再拣选到发布分支;
  • 发布分支禁止 rebase、禁止 force。

热更在打出热更包的那次提交上加 Tag,四段式,例如 releases/android/1.1.0.1(第几次热更就写几)。整包存档、热更 Tag 的配套步骤按团队流程执行,不在本文展开。

工作区规范

  1. 工作区默认必须是干净的(Clean)。 用 Unity 打开工程后,不能有任何不相关的文件改动,而且能直接进入游戏。开发人员必须始终保持这个状态;不干净时立即清理,避免把本地垃圾扩散成别人的问题。
  2. 不需要纳入版本控制的文件用 .gitignore 忽略。 如果只是自己本地的文件,用 .git/info/exclude,不要把个人忽略规则写进仓库的 .gitignore。引擎缓存和打包产物(如 Library/、Temp/、Logs/ 和打包输出目录)已经在 .gitignore 里,不要提交。
  3. 理论上,所有出现在工作区、又不该被忽略的文件都需要提交。 看见却不提交,等于给别人留地雷。Unity 资源改动必须连同对应 .meta 一起提交;如果团队装了本地 .meta 检查钩子,漏了会被拦住,实现思路见 Unity 提交时检查 meta 文件。
  4. 不要改 .gitattributes 去转换 .asset 的换行。 .asset 可能是文本也可能是二进制,乱转行尾会把整个文件变成一次无意义 diff。相关背景见 Git 自动转换文件换行符。

附录 A:程序日常操作

按 Fork 界面写步骤,命令只作对照。为什么这样,见正文「合并提交」和「推送与 force」。

第一次

  1. 安装 Fork。姓名用中文全名,邮箱用工作邮箱。
  2. 第一次 Pull 勾选并保持:
    • Rebase instead of merge
    • Stash and reapply local changes
  3. 如果团队装了 .meta 检查钩子,按仓库说明安装。它只检查 Unity 资源与 .meta 是否成对,不是服务器钩子;实现思路见 Unity 提交时检查 meta 文件。
  4. Ctrl+Shift+A:历史只显示当前分支,日常更干净。
  5. 任务单跳转:由仓库维护者在 Fork 里配置 Task ID / Bug ID 的链接模式,指向 TAPD、Jira 等任务系统。

主干日常

小修复、表、资源、不会破坏「打开就能玩」的改动,直接在 main 上做,流程与策划相同:提交 → Ctrl+Pull → Ctrl+Push。

提交说明第一行:

1 2 
Task ID1000001 修复登录卡死 Bug ID1000002 修正图标偏移 

工作区不干净时不要 rebase、不要切分支去合入。先提交、丢弃或 stash,让左边文件列表空掉。

功能分支生命周期

一条分支由一个人负责,可以多人共用。命名空间是负责人,不是「仅此人可推」。

谁 可以做 不要做
负责人 建分支、每天 rebase 同步 main、force-with-lease、--no-ff 合入、删除分支 force main
共用者 在该分支上提交并推送;负责人同步之后再拉再改 自己 rebase 主干再 force 这条分支

从最新 main 建分支

  1. 先切到 main,Ctrl+Pull,确认已在最新主干。
  2. 新建分支,名称:
1 
负责人姓名全拼/日期-英文说明 

例如: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)。

负责人:每天同步主干

最少每天一次。冲突当天找改同一文件的人,记忆还清楚。

  1. 工作区干净。
  2. 大规模改脚本前退出 Unity Play。
  3. 把当前功能分支 rebase 到最新 main(Fork 的 Rebase 或 Lean Branching 的 Sync)。
  4. 只有负责人在 rebase 之后对该远程功能分支 force-with-lease。
  5. 同步完成后通知共用者:先 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 把主干拉进来。

负责人:合入主干

  1. 功能分支已 rebase 到最新 main,工作区干净。
  2. 切到 main,Ctrl+Pull。
  3. Merge 功能分支,创建合并提交(--no-ff)。即使功能分支只有一个提交,也不允许快进。
  4. 推 main(普通 Push,不是 force)。
  5. 删除本地和远程功能分支。

对照:

1 2 3 4 5 6 
git checkout main git pull --rebase git merge --no-ff zhangsan/20261029-startup-time-optimization git push origin main git branch -d zhangsan/20261029-startup-time-optimization git push origin --delete zhangsan/20261029-startup-time-optimization 

不要 squash 合入主干。合并提交说明可以用 Merge branch 'zhangsan/20261029-startup-time-optimization',Issue 已经写在功能提交里。

发布

  1. 从最新 main 切发布分支:
1 2 
releases/android/1.4.0 releases/ios/1.4.0 

  1. 之后进入该版本的内容只做拣选(cherry-pick),不要把功能分支 merge 进发布分支。
  2. 发布分支禁止 rebase、禁止 force。
  3. 发布上发现的问题:先在 main 修并推上去,再把那次提交拣选到发布分支。不要在发布分支上开新功能,也不要把发布分支 merge 回 main。
  4. 热更 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,不要强制添加。

停手清单

出现下面情况,停手找人。文档不教补救步骤(符合「规避而不是救火」):

  1. 已经 force 了 main 或 releases/*
  2. 在发布分支上开了新功能,而主干没有
  3. 把发布分支 merge 回了 main
  4. 对已经推上主干的提交做 interactive rebase / Amend
  5. 自己做历史重写(filter-branch、filter-repo 等)
  6. rebase 做到一半,历史既不是功能分支也不是主干

日常禁止、但还没铸成大错时自己停下来即可:

  • 用 Fork Finish 快进合入主干
  • squash 合入主干
  • 共用者自己 rebase 主干再 force 功能分支
  • 工作区不干净时 rebase

附录 B:策划 / 美术 / QA 最少步骤

只讲日常要用的最少步骤。默认只在主干 main 上工作,不要自己新建分支。遇到冲突、合错、推送失败,找程序处理。

  1. 第一次:安装 Fork;姓名必须用中文全名,邮箱用工作邮箱;让程序给你仓库地址,用 Fork 打开,不要自己用命令行克隆;第一次 Pull 勾选 Rebase instead of merge 和 Stash and reapply local changes,之后保持。
  2. 提交:看整个工作区,勾选要提交的文件;改了 Unity 资源,对应的 .meta 一起勾上;提交说明第一行按 Task ID1000001 调整新手引导文案 / Bug ID1000002 修正图标偏移 的格式写;点 Commit。
  3. 拉取和推送:先 Ctrl+Pull,再 Ctrl+Push;有未提交的本地改动也可以 Pull,Fork 会先藏起来再放回来;Push 被拒先 Ctrl+Pull,仍失败就停手找程序,不要点 Force。
  4. 工作区必须干净:左边文件列表没有改动就是干净;用 Unity 打开工程后不能有不相关的改动,而且必须能直接进游戏;不干净立刻清理;误改的文件用 Fork 的 Discard 丢弃,不确定找程序。
  5. 弹出冲突:不要点「采用我的 / 采用他们的」,不要自己改冲突标记,停手找程序。
  6. 修改文件名大小写:Windows 不区分大小写,直接把 Icon.png 改成 icon.png,Git 经常当没改过。先改成临时名(如 icon_tmp.png)提交一次,再改回正确大小写提交一次;.meta 文件名也要一起改、一起提交。
  7. 不要做这些:不要自己新建分支;不要用 SourceTree、TortoiseGit;不要在某个子目录里单独提交;不要取消 Rebase instead of merge;不要长期留着脏工作区;不要 Force Push;冲突时不要自己选「采用我的 / 采用他们的」。
  8. 做完自己的改动:提交 → Ctrl+Pull → Ctrl+Push;做完应能直接进游戏。

版权声明:
作者:dingding
链接:https://www.techfm.club/p/239372.html
来源:TechFM
文章版权归作者所有,未经允许请勿转载。

THE END
分享
二维码
< <上一篇
下一篇>>