# 团队 Git 协作

本参考用于多人在同一仓库或多个相关仓库中开发、验证和交付改动。分支名称、集成环境和合并权限以当前仓库的 `AGENTS.md`、分支保护规则和团队约定为准；下面的 `main`、`test` 和功能分支只是说明流程的例子，不是每个项目都必须建立的三层分支。

## 先分清提交、分支和远端

- **提交（commit）**记录一次可追踪的代码状态。提交说明应概括实际改动，便于审阅和定位历史；提交不是自动备份到服务器，未推送的提交仍只在本地。
- **分支（branch）**是指向某次提交的可移动名称。功能分支让一项改动有独立的工作线，但最终是否合入集成分支、何时发布，由项目流程决定。多个分支通常共享大部分历史，不会为每个分支完整复制一份仓库。
- **本地分支**和 `origin/<分支>` 是不同的引用。`origin` 只是常见的远端名称；本地提交不会自动到远端，其他人的远端提交也不会自动进入当前工作分支。

`git fetch` 更新本地看到的远端引用，不改动当前分支；`git pull` 在获取远端更新后，还会尝试将其整合进当前分支；`git push` 把本地提交发送到远端。先看清当前分支和差异，再决定需要哪一步，不能把“同步”理解成无条件的双向合并。

## 按项目规模选择分支流程

小型、低并发项目可以在受控的主开发分支上完成短改动，用自动检查和小提交保持可回顾。多人并行或主分支受保护时，通常从约定的集成基线创建短生命周期功能分支，完成验证与审阅后通过合并请求集成。

只有项目确实有独立测试环境和对应发布流程时，才需要长期维护 `test` 一类集成分支。此时可以约定“功能分支 → 测试分支 → 发布分支”，但 Git 本身不禁止 `test` 合入 `main`；是否允许、由谁批准以及何时部署，是仓库策略而不是 Git 的固定规则。发布分支出现热修复后，也要按项目流程把修复带回后续开发基线，不能假定所有分支自动保持一致。

## 完成一项改动

1. 查看 `git status`、当前分支及远端更新，从团队约定的最新基线开始。已有未提交改动时先辨认归属，不覆盖他人的工作。只有需要并行开发或受保护流程时才新建功能分支，名称简短描述任务。
2. 在该分支开发并本地启动受影响的应用。检查实际页面、接口或任务链路，而不是仅凭“服务已启动”判断功能完成。测试环境则以项目现有 CI、部署和验收流程为准。
3. 完成后运行与风险相称的检查，只暂存本任务文件，复核差异，再提交带有清楚说明的原子改动。一个功能可以有多个有意义的提交，但不要把无法运行的保存点当作交付。
4. 获得推送授权后推送分支；按仓库规则发起合并请求，等待自动检查、冲突处理和必要审阅。合入测试或主分支与部署是不同动作，不能因合并成功就声称已上线。

提交、暂存审阅和作者身份的细则见 [Git、资源与持久化](git-repository-and-assets.md)。

## 冲突与回退

两个人修改同一文件不一定冲突；真正的冲突出现在 Git 无法自动整合的重叠改动，也可能涉及文件移动或删除。并行开发时先在自己的分支完成改动，准备集成前获取目标分支的最新状态，再按项目约定合并或变基。发生冲突时先理解两边意图，与相关负责人确认保留的行为，再编辑冲突位置、运行受影响的检查并完成合并。不要只为消除冲突标记就任意保留一边，也不要把自己功能分支中的未完成工作反向合入共享分支。

需要撤销共享分支上的某次代码改动时，先确定目标提交、后续依赖和发布状态，通常通过新的 `git revert` 提交保留历史。`git reset` 只适合明确属于自己的未共享本地历史；改写或强推共享分支会影响其他协作者，必须另行获得明确授权。代码回退也不会自动撤销已执行的数据库迁移或外部副作用。

## 多仓库与文件资源

一个功能跨前端、后端或小程序等多个仓库时，只检出需要修改和验证的仓库；每个仓库分别提交与审阅，并约定接口契约、兼容顺序和联调环境。不必为了让 Agent 找到代码就把所有仓库都拉到本机，更不要跨仓库假设一次提交能原子发布全部改动。

`.gitignore` 应排除实际产生的依赖、构建输出、日志、环境配置和临时文件，但不能代替提交前审阅。锁文件、源码、迁移、资源清单和处理脚本仍应按项目规则纳入版本控制；二进制资源不直接进入 Git，使用受管理的对象存储。具体边界和示例见 [Git、资源与持久化](git-repository-and-assets.md)。

## 来源与适用边界

本文从团队 Git 协作与核心概念的截图笔记中提炼可迁移的部分。截图中的具体仓库、提交、分支流转和测试环境只是示例；本文不将它们设为其他项目的默认流程。