wren
853 lines
23 KiB
Markdown
853 lines
23 KiB
Markdown
# 团队 Git 协作完整规范
|
||
|
||
> 适用对象：个人项目、小项目、大项目
|
||
> 版本：v1.0 · 2026-05-07
|
||
|
||
---
|
||
|
||
## 一、核心原则
|
||
|
||
不论团队规模大小，所有 Git 协作都遵守以下 5 条铁律：
|
||
|
||
1. **主干（main）永远可发布**
|
||
2. **凡是会影响他人的操作，事前通知、事中可见、事后可恢复**
|
||
3. **分支属于"任务"，不属于"人"**（详见第六章）
|
||
4. **推送前先同步**：`git pull --rebase` 后再 `git push`
|
||
5. **重要分支禁止直接 push，必须走 PR**
|
||
|
||
---
|
||
|
||
## 二、如何选择工作流
|
||
|
||
### 决策树
|
||
|
||
```
|
||
你一个人做这个项目吗？
|
||
├─ 是 → 【方案 A】个人极简流
|
||
└─ 否 → 团队 ≥ 6 人 或 同时维护多版本？
|
||
├─ 是 → 【方案 C】Git Flow Lite（带 develop）
|
||
└─ 否 → 【方案 B】GitHub Flow（90% 小项目适用）
|
||
```
|
||
|
||
### 三种方案对比
|
||
|
||
| 维度 | A·个人 | B·小项目 | C·大项目 |
|
||
|------|--------|---------|---------|
|
||
| 团队规模 | 1 人 | 2-5 人 | 6+ 人 |
|
||
| 主分支 | main | main | main + develop |
|
||
| 是否需 develop | ❌ | ❌ | ✅ |
|
||
| 是否需 release 分支 | ❌ | ❌ | ✅（可选） |
|
||
| 是否需 hotfix 分支 | ❌ | ✅ | ✅ |
|
||
| 部署策略 | 手动 / tag | 持续部署 | 阶段部署 |
|
||
| 发布周期 | 不固定 | 随时 | 双周 / 月度 |
|
||
| PR Review | 自看 | ≥1 人 | ≥2 人 |
|
||
| 复杂度 | ★ | ★★ | ★★★★ |
|
||
|
||
### 升级信号
|
||
|
||
**A → B**：第二个人加入，立刻配 main 保护 + PR 流程。
|
||
|
||
**B → C**：满足以下任一即升级
|
||
- 同时维护多个版本（v1 还在用，v2 在开发）
|
||
- 有专门 QA 阶段，main 不能合并即上线
|
||
- 发布周期 ≥ 2 周
|
||
- 团队 ≥ 6 人
|
||
|
||
> ⚠️ **宁可滞后升级，也不要预防性复杂化**。多数团队过度设计，把简单事搞复杂。
|
||
|
||
---
|
||
|
||
## 三、方案 A：个人项目工作流
|
||
|
||
### 分支模型
|
||
|
||
```
|
||
main (主线 + 发布锚点)
|
||
└─ feature/* (按需，仅用于实验性大改动)
|
||
```
|
||
|
||
### 日常工作流
|
||
|
||
**小改动 → 直接上 main**
|
||
|
||
```bash
|
||
git add .
|
||
git commit -m "fix: 修复登录按钮样式"
|
||
git push
|
||
```
|
||
|
||
**大改动 / 不确定的实验 → 开分支保命**
|
||
|
||
```bash
|
||
git checkout -b feature/重构数据层
|
||
# ...开发...
|
||
|
||
# 没问题 → 合并
|
||
git checkout main
|
||
git merge --no-ff feature/重构数据层
|
||
git push
|
||
git branch -d feature/重构数据层
|
||
|
||
# 实验失败 → 直接丢弃
|
||
git checkout main
|
||
git branch -D feature/重构数据层
|
||
```
|
||
|
||
### 发布流程
|
||
|
||
```bash
|
||
git tag -a v1.2.0 -m "release: v1.2.0 - 评查详情页上线"
|
||
git push --tags
|
||
```
|
||
|
||
**版本号遵循 [SemVer](https://semver.org/)**：
|
||
- `v主版本.次版本.补丁`
|
||
- 主版本：不兼容改动
|
||
- 次版本：新功能（向下兼容）
|
||
- 补丁：bug 修复
|
||
|
||
### 个人项目最低纪律
|
||
|
||
| 习惯 | 价值 |
|
||
|------|------|
|
||
| 每天 push 到远程 | 硬盘坏了不丢工 |
|
||
| commit 信息写人话 | 半年后能看懂 |
|
||
| 重大改动前打 tag | 有回滚锚点 |
|
||
| README 记录关键决策 | 时间久了不抓瞎 |
|
||
| `.gitignore` 配齐 | 不把密钥推上去 |
|
||
|
||
### 不要做的事
|
||
|
||
- ❌ `git commit -m "update"` / `"修改"` / `"123"`
|
||
- ❌ 一周不 push
|
||
- ❌ 在 main 上做不确定的实验
|
||
- ❌ 把 `.env` 推到远程
|
||
|
||
---
|
||
|
||
## 四、方案 B：小项目工作流（GitHub Flow）
|
||
|
||
**适用：2-5 人，持续部署**
|
||
|
||
### 分支模型
|
||
|
||
```
|
||
main (受保护，PR 合并，自动部署到生产)
|
||
├─ feature/评查详情页
|
||
├─ fix/登录闪退
|
||
└─ hotfix/支付失败 (紧急修生产)
|
||
```
|
||
|
||
**核心思想**：
|
||
- main 永远可发布
|
||
- feature 分支**生命周期短**（1-3 天最佳，最长 1 周）
|
||
- 所有改动走 PR
|
||
|
||
### 日常工作流（每个任务都按这个跑）
|
||
|
||
```bash
|
||
# 1. 开分支前先同步 main
|
||
git checkout main
|
||
git pull --rebase
|
||
|
||
# 2. 创建任务分支（任务命名，不要带人名）
|
||
git checkout -b feature/评查详情页
|
||
|
||
# 3. 开发，频繁小步提交，频繁推送
|
||
git add .
|
||
git commit -m "feat(评查): 新增详情页骨架"
|
||
git push -u origin feature/评查详情页
|
||
|
||
# 4. 推送前同步 main，避免冲突堆积
|
||
git fetch origin
|
||
git rebase origin/main
|
||
# 解决冲突 → 本地测试通过
|
||
|
||
# 5. 推送（rebase 后需要 force-with-lease）
|
||
git push --force-with-lease
|
||
|
||
# 6. 提 PR → Review → 合并 → 自动部署
|
||
|
||
# 7. 合并后清理本地
|
||
git checkout main
|
||
git pull
|
||
git branch -d feature/评查详情页
|
||
```
|
||
|
||
### PR 流程规范
|
||
|
||
**提 PR 时**：
|
||
- 标题：`<type>(<scope>): <简短描述>`，例：`feat(评查): 新增详情页`
|
||
- 描述模板：
|
||
```markdown
|
||
## 改动内容
|
||
- ...
|
||
|
||
## 测试方法
|
||
- ...
|
||
|
||
## 截图（如有 UI 改动）
|
||
|
||
## 关联 Issue
|
||
Closes #123
|
||
```
|
||
- 自检：lint 通过、测试通过、不含调试代码
|
||
|
||
**Review 时**：
|
||
- 24 小时内响应
|
||
- 给具体可操作的反馈，不要"建议优化一下"
|
||
- Approve 前自己心里跑一遍代码逻辑
|
||
|
||
### 紧急修复（hotfix）
|
||
|
||
```bash
|
||
git checkout main && git pull
|
||
git checkout -b hotfix/支付失败
|
||
# 修 → 测 → push → PR → 紧急合并 → 立即部署
|
||
```
|
||
|
||
### 仓库一次性配置（落地关键）
|
||
|
||
**main 分支保护（GitHub/GitLab 后台）**：
|
||
- ✅ 禁止直接 push
|
||
- ✅ 禁止 force push
|
||
- ✅ 必须 PR + ≥1 Approve
|
||
- ✅ 必须通过 CI（lint + test）
|
||
- ✅ 合并后自动删除分支
|
||
|
||
---
|
||
|
||
## 五、方案 C：大项目工作流（Git Flow Lite）
|
||
|
||
**适用：6+ 人 / 多版本并存 / 有 QA 测试期**
|
||
|
||
### 分支模型
|
||
|
||
```
|
||
main (生产版本，受保护，只接受来自 release/hotfix 的合并)
|
||
└─ develop (开发主线，受保护，所有 feature 合并到这里)
|
||
├─ feature/评查详情页 (个人功能分支)
|
||
├─ feature/登录优化
|
||
├─ release/v2.3.0 (准备发布的快照分支)
|
||
└─ hotfix/支付失败 (从 main 拉，修完合并回 main + develop)
|
||
```
|
||
|
||
### 各分支角色
|
||
|
||
| 分支 | 来源 | 合并去向 | 生命周期 |
|
||
|------|------|---------|---------|
|
||
| `main` | 永久 | — | 永久 |
|
||
| `develop` | 永久 | — | 永久 |
|
||
| `feature/*` | develop | develop | 任务期 |
|
||
| `release/*` | develop | main + develop | 发布周期 |
|
||
| `hotfix/*` | main | main + develop | 紧急修复 |
|
||
|
||
### develop 的角色
|
||
|
||
- **开发主线**：所有 feature 合并到 develop
|
||
- **集成测试环境**：QA 在 develop 上测试
|
||
- **不直接发布**：发布前从 develop 拉 release 分支封板
|
||
|
||
### release 分支：发布前的"封板"
|
||
|
||
```bash
|
||
# 1. 从 develop 拉 release 分支（功能冻结）
|
||
git checkout develop && git pull
|
||
git checkout -b release/v2.3.0
|
||
|
||
# 2. 在 release 上只修 bug，不加新功能
|
||
# QA 测试 → 修 bug → 改版本号 → 写 changelog
|
||
|
||
# 3. 测试通过，合并到 main 并打 tag
|
||
git checkout main && git pull
|
||
git merge --no-ff release/v2.3.0
|
||
git tag -a v2.3.0 -m "release: v2.3.0"
|
||
git push --tags
|
||
|
||
# 4. 合并回 develop（带上 release 上的 bug 修复）
|
||
git checkout develop
|
||
git merge --no-ff release/v2.3.0
|
||
git push
|
||
|
||
# 5. 删除 release 分支
|
||
git branch -d release/v2.3.0
|
||
```
|
||
|
||
### hotfix 分支：紧急修生产
|
||
|
||
```bash
|
||
# 1. 从 main 拉 hotfix 分支
|
||
git checkout main && git pull
|
||
git checkout -b hotfix/支付失败
|
||
|
||
# 2. 修 → 测 → 提 PR
|
||
|
||
# 3. 合并到 main 并打 patch tag
|
||
git checkout main
|
||
git merge --no-ff hotfix/支付失败
|
||
git tag -a v2.3.1 -m "hotfix: 修复支付失败"
|
||
git push --tags
|
||
|
||
# 4. 必须合并回 develop！否则下次发布 bug 复发
|
||
git checkout develop
|
||
git merge --no-ff hotfix/支付失败
|
||
git push
|
||
|
||
# 5. 删除 hotfix 分支
|
||
git branch -d hotfix/支付失败
|
||
```
|
||
|
||
### 日常 feature 工作流
|
||
|
||
```bash
|
||
# 从 develop（不是 main！）开分支
|
||
git checkout develop && git pull --rebase
|
||
git checkout -b feature/评查详情页
|
||
|
||
# 开发 → 推送 → PR 到 develop（不是 main！）
|
||
git push -u origin feature/评查详情页
|
||
# 提 PR：feature/评查详情页 → develop
|
||
```
|
||
|
||
### 大项目仓库配置
|
||
|
||
- **main**：禁止 push、禁止 force push、只接受 release/hotfix 合并、必须 ≥2 Approve
|
||
- **develop**：禁止 push、必须 PR + ≥1 Approve、必须通过 CI
|
||
- **CI 要求**：lint + 单元测试 + 集成测试 + 静态分析
|
||
|
||
---
|
||
|
||
## 六、为什么禁止使用个人分支【专题】
|
||
|
||
### 反模式（团队中常见错误）
|
||
|
||
```
|
||
❌ feature/评查详情页-zhangsan
|
||
❌ zhangsan-dev
|
||
❌ feature/zhangsan/xxx
|
||
❌ 张三的分支
|
||
❌ wy-dev / wy-test
|
||
```
|
||
|
||
### 5 大问题
|
||
|
||
#### 1️⃣ 强化"个人所有权"，破坏协作精神
|
||
|
||
分支带人名 → 同事潜意识"这是张三的地盘，我别动" → 协作变独行 → 出问题没人帮看。
|
||
|
||
**好的协作是任务驱动**：分支属于任务，谁有空谁接手。
|
||
|
||
#### 2️⃣ 离职、休假、轮岗时难交接
|
||
|
||
**真实场景**：
|
||
> 张三休假一周，留下 5 条 `feature/xxx-zhangsan` 分支。李四接手时是改名（影响远程）、还是新开 `feature/xxx-lisi`（造成分裂）？怎么处理都别扭。
|
||
|
||
如果分支叫 `feature/评查详情页`，李四直接 `git checkout` 接着干，**零摩擦**。
|
||
|
||
#### 3️⃣ 分支语义模糊，看名字不知道做什么
|
||
|
||
`zhangsan-dev` 这条分支在做啥？
|
||
- 评查模块？
|
||
- 登录优化？
|
||
- 性能调优？
|
||
- 还是张三的"我啥都往这塞"草稿？
|
||
|
||
**好的分支名 = 一句话任务说明**，看到 `feature/评查详情页` 立刻明白。
|
||
|
||
#### 4️⃣ 容易堆积成"杂物分支"
|
||
|
||
人名分支没有边界，张三会把"评查详情页 + 顺手优化的登录 + 试验性能改动"都塞进 `feature/zhangsan-dev`。结果：
|
||
- PR 改动巨大，没人能 Review
|
||
- 一个 bug 拖延了三个功能
|
||
- 不能单独 revert 某项改动
|
||
|
||
**任务分支天然有边界**：`feature/评查详情页` 只装评查相关改动，超出范围就该开新分支。
|
||
|
||
#### 5️⃣ 多人协作同一功能时命名混乱
|
||
|
||
**真实场景**：
|
||
> 评查详情页很大，张三李四王五一起做。分支会变成：
|
||
> - `feature/评查详情页-zhangsan`
|
||
> - `feature/评查详情页-lisi`
|
||
> - `feature/评查详情页-wangwu`
|
||
>
|
||
> 三人改动如何同步？合并顺序？谁先合谁后合？混乱。
|
||
|
||
**正确做法**：开一条父分支 `feature/评查详情页`，每人开**子任务分支**：
|
||
- `feature/评查详情页-头部`
|
||
- `feature/评查详情页-列表`
|
||
- `feature/评查详情页-筛选`
|
||
|
||
子任务都合并回父分支，最后父分支整体合到 develop。
|
||
|
||
---
|
||
|
||
### 真实案例：人名分支造成的事故
|
||
|
||
**案例 1：交接黑洞**
|
||
> 某团队张三离职前留下 `zhangsan/refactor-payment` 分支，里面有他重构支付的工作（约 60% 完成）。半年后团队想接着做，发现：分支与 main 已差异巨大，无法 rebase；分支内 commit 信息全是"WIP"，没人知道每个 commit 在做什么；最终只能放弃，**重做**。
|
||
|
||
**案例 2：紧急修复无法落地**
|
||
> 周五晚上生产支付功能挂了。值班发现修复需要改一个文件，但该文件在 `feature/支付重构-zhangsan` 分支上张三已改了一周。要么强行修生产（与张三的分支冲突会变大），要么等张三周一来。最终用了一个肮脏的 hotfix，**技术债累计**。
|
||
|
||
**案例 3：PR Review 无人能审**
|
||
> `feature/zhangsan-dev` 一个 PR 改了 2000 行，包含评查、登录、列表、性能 4 个不相关的改动。Review 同事看了一上午放弃，盖章通过。两天后线上 bug，**无法定位是哪个改动引起的**。
|
||
|
||
---
|
||
|
||
### 正确做法
|
||
|
||
#### ✅ 任务命名规范
|
||
|
||
```
|
||
feature/<任务描述> feature/评查详情页
|
||
feature/<issue号>-<描述> feature/PROJ-123-评查详情页
|
||
fix/<bug简述> fix/登录闪退
|
||
hotfix/<紧急bug> hotfix/支付失败
|
||
refactor/<范围> refactor/数据层
|
||
```
|
||
|
||
#### ✅ 任务归属体现在 PR/Issue Assignee
|
||
|
||
谁负责这个任务 → 在 **PR/Issue 的 Assignee** 字段标记，不要污染分支名。
|
||
|
||
#### ✅ 分支只与「任务/目标」关联
|
||
|
||
看到 `feature/评查详情页` 应当能立刻回答：
|
||
- 这条分支在做什么
|
||
- 合并目标是什么
|
||
- 何时该删除
|
||
|
||
---
|
||
|
||
### 例外：可以带人名的场景
|
||
|
||
**仅限以下短期、可丢弃的情况**：
|
||
|
||
#### 1. 个人探索/草稿分支（明确不打算合并）
|
||
|
||
```
|
||
zhangsan/试个性能方案
|
||
zhangsan/sandbox
|
||
```
|
||
|
||
用斜线作为"个人 sandbox 命名空间"前缀，与正式 feature 分支区分。
|
||
|
||
#### 2. Fork 工作流（开源项目常见）
|
||
|
||
你 fork 仓库到自己账号后，分支名随意，提 PR 时再说。这是**远程 fork 模式**，不属于"单仓库协作"场景。
|
||
|
||
#### 3. 多人并行试方案的临时区分
|
||
|
||
```
|
||
feature/评查详情页/方案A-zhangsan
|
||
feature/评查详情页/方案B-lisi
|
||
```
|
||
|
||
验证完保留赢的方案，删除全部分支，重命名为正式分支。
|
||
|
||
> **核心：这些场景都是短期、明确不污染主流分支的。**
|
||
|
||
---
|
||
|
||
## 七、通用规范
|
||
|
||
### 分支命名
|
||
|
||
```
|
||
<type>/<description>
|
||
<type>/<issue-id>-<description>
|
||
```
|
||
|
||
**type 类型**：
|
||
- `feature/` 新功能
|
||
- `fix/` bug 修复
|
||
- `hotfix/` 紧急修复（生产）
|
||
- `refactor/` 重构
|
||
- `docs/` 文档
|
||
- `test/` 测试
|
||
- `chore/` 杂项（依赖升级、配置）
|
||
- `release/` 发布分支（仅 Git Flow）
|
||
|
||
**示例**：
|
||
```
|
||
feature/评查详情页
|
||
feature/PROJ-123-评查详情页
|
||
fix/登录闪退
|
||
hotfix/v2.3-支付失败
|
||
```
|
||
|
||
**禁止**：
|
||
- ❌ 人名前缀/后缀
|
||
- ❌ 拼音缩写如 `wy-dev`
|
||
- ❌ 没有 type 前缀
|
||
- ❌ 空格、特殊字符
|
||
|
||
### 提交信息（Conventional Commits）
|
||
|
||
```
|
||
<type>(<scope>): <简短描述>
|
||
|
||
<可选详细说明>
|
||
|
||
<可选 footer>
|
||
```
|
||
|
||
**type**：
|
||
- `feat:` 新功能
|
||
- `fix:` 修 bug
|
||
- `refactor:` 重构（不改外部行为）
|
||
- `perf:` 性能优化
|
||
- `test:` 测试
|
||
- `docs:` 文档
|
||
- `style:` 格式（不改代码逻辑）
|
||
- `chore:` 杂项
|
||
- `build:` 构建相关
|
||
- `ci:` CI 相关
|
||
|
||
**示例**：
|
||
```
|
||
feat(评查): 新增详情页骨架屏
|
||
|
||
- 添加加载占位组件
|
||
- 实现进入动画
|
||
- 适配移动端
|
||
|
||
Closes #123
|
||
```
|
||
|
||
**禁止**：
|
||
- ❌ `update`、`fix`、`修改`、`123`
|
||
- ❌ 一个 commit 改 N 个不相关的事
|
||
- ❌ `WIP`（合并前应 squash 掉）
|
||
|
||
### 标签（Tag）规范
|
||
|
||
**版本标签**遵循 [SemVer](https://semver.org/)：
|
||
```
|
||
v1.2.3 正式版
|
||
v1.2.3-beta.1 beta 版
|
||
v1.2.3-rc.1 发布候选版
|
||
```
|
||
|
||
**打 tag 时机**：
|
||
- 个人项目：每次发布
|
||
- 小项目：每次部署到生产
|
||
- 大项目：release 合并到 main 时
|
||
|
||
### .gitignore 通用模板
|
||
|
||
```gitignore
|
||
# 依赖
|
||
node_modules/
|
||
__pycache__/
|
||
*.pyc
|
||
venv/
|
||
.venv/
|
||
|
||
# 环境变量（永远不要提交）
|
||
.env
|
||
.env.*
|
||
!.env.example
|
||
|
||
# 编辑器
|
||
.vscode/
|
||
.idea/
|
||
*.swp
|
||
.DS_Store
|
||
|
||
# 构建产物
|
||
dist/
|
||
build/
|
||
*.log
|
||
coverage/
|
||
|
||
# 本地配置
|
||
.cache/
|
||
*.local
|
||
```
|
||
|
||
---
|
||
|
||
## 八、共享资源协作守则
|
||
|
||
### 通用原则
|
||
|
||
> **凡是会影响他人的操作，事前通知、事中可见、事后可恢复。**
|
||
|
||
### 共享资源守则表
|
||
|
||
| 共享资源 | 守则 |
|
||
|---------|------|
|
||
| 共享开发/测试机 | 默认主分支；切换通知；用完还原；优先 `git worktree` |
|
||
| 共享数据库 | 不在共用库做破坏性改动；每人独立 schema；测试用 docker 起本地 |
|
||
| 共享 API Key / Secret | 用 secret manager；禁止贴 IM/代码/截图 |
|
||
| CI/CD pipeline | 改流水线前通知；不在大家忙时触发昂贵任务 |
|
||
| 第三方账号 | SSO + 审计；操作记录可追溯 |
|
||
| 部署环境 | 部署窗口公告；锁机制（谁部署谁举手） |
|
||
|
||
### 切换共享资源的标准动作
|
||
|
||
```
|
||
1. 群里通知："我要 [操作] [资源]，预计 [时间]"
|
||
2. 操作
|
||
3. 用完恢复默认状态
|
||
4. 群里告知："已恢复"
|
||
```
|
||
|
||
### 优先用隔离手段，而不是切换
|
||
|
||
```bash
|
||
# git worktree：在不同目录跑不同分支，主目录不动
|
||
git worktree add ../preview-xxx feature/xxx
|
||
git worktree remove ../preview-xxx
|
||
|
||
# Docker：每个分支起独立容器
|
||
docker compose -p preview-xxx up
|
||
```
|
||
|
||
### 终极方案：消除"共享"本身
|
||
|
||
- 每个 PR 自动起一个独立预览环境（Vercel / Netlify / K8s preview）
|
||
- 每人独立数据库 schema（自动迁移）
|
||
- 每人独立云资源（云厂商沙盒账号）
|
||
|
||
> **根本不需要"共享调试机"。**
|
||
|
||
---
|
||
|
||
## 九、常见问题 FAQ
|
||
|
||
### Q1：合并前应该用 merge 还是 rebase？
|
||
|
||
| 场景 | 推荐 |
|
||
|------|------|
|
||
| 个人 feature 分支同步 main | `git rebase`（历史干净） |
|
||
| 多人协作的分支 | `git merge`（不重写他人 commit） |
|
||
| 合并 PR 到 main | **Squash and merge**（main 历史干净） |
|
||
| 已推送的分支 | 谨慎使用 rebase，需 `--force-with-lease` |
|
||
|
||
### Q2：feature 分支多久合并一次？
|
||
|
||
- **理想**：1-3 天
|
||
- **可接受**：1 周
|
||
- **超过 1 周必须警惕**：分支过大 → 拆分；同步频率提高（每天 rebase main）
|
||
|
||
### Q3：commit 太多太乱怎么办？
|
||
|
||
合并到主分支前 squash 整理：
|
||
```bash
|
||
git rebase -i HEAD~5
|
||
# 把第二个开始的 pick 改成 squash 或 fixup
|
||
```
|
||
|
||
或在 PR 合并时选择 **"Squash and merge"**。
|
||
|
||
### Q4：误推了敏感信息（密钥）怎么办？
|
||
|
||
1. **立即作废**这个密钥（去后台重新生成）
|
||
2. 用 `git filter-repo` 或 BFG 清除历史
|
||
3. **强制推送**所有分支
|
||
4. **通知所有人**重新 clone
|
||
|
||
预防：
|
||
- `.gitignore` 配齐 `.env`
|
||
- 用 secret manager
|
||
- 装 `git-secrets` / `gitleaks` pre-commit 钩子
|
||
|
||
### Q5：rebase 时遇到冲突怎么办？
|
||
|
||
```bash
|
||
# 1. 解决冲突文件
|
||
# 2. git add <冲突文件>
|
||
# 3. git rebase --continue
|
||
|
||
# 实在搞不定就放弃
|
||
git rebase --abort
|
||
```
|
||
|
||
### Q6：误删了分支怎么恢复？
|
||
|
||
```bash
|
||
# 找到最后一次 commit
|
||
git reflog
|
||
|
||
# 恢复
|
||
git checkout -b feature/xxx <commit-sha>
|
||
```
|
||
|
||
### Q7：`git push` 被拒（rejected）
|
||
|
||
意味着远程分支有新 commit 你本地没有。
|
||
|
||
```bash
|
||
# 同步后再推
|
||
git pull --rebase
|
||
git push
|
||
|
||
# 如果是 rebase 后推自己的分支
|
||
git push --force-with-lease # 注意是 --force-with-lease，不是 --force
|
||
```
|
||
|
||
> ⚠️ **永远不要对 main / develop 用 `--force`！**
|
||
|
||
### Q8：什么时候删分支？
|
||
|
||
- 合并到主干后**立即删除**远程和本地
|
||
- GitHub/GitLab 可设置"合并后自动删除"
|
||
- 本地：`git branch -d feature/xxx`
|
||
|
||
### Q9：长期废弃的分支能直接删吗？
|
||
|
||
先 `git log feature/xxx` 看是否有未合并 commit。若有：
|
||
- 询问作者是否还需要
|
||
- 或导出 patch：`git format-patch main..feature/xxx`
|
||
|
||
### Q10：Reviewer 检查清单
|
||
|
||
审视 PR 是否值得合并：
|
||
|
||
- [ ] 分支命名规范，无人名
|
||
- [ ] 改动只做一件事，与 PR 标题一致
|
||
- [ ] 提交信息规范
|
||
- [ ] 测试覆盖关键路径
|
||
- [ ] CI 全绿
|
||
- [ ] 无调试代码（console.log、注释掉的代码）
|
||
- [ ] 无敏感信息（API Key、密码）
|
||
- [ ] 文档/注释 同步更新
|
||
- [ ] 跑过本地测试
|
||
|
||
---
|
||
|
||
## 十、配套工具与一键配置
|
||
|
||
### 全员 Git 配置（每台机器跑一次）
|
||
|
||
```bash
|
||
# pull 默认 rebase（避免无意义 merge commit）
|
||
git config --global pull.rebase true
|
||
|
||
# push 自动追踪上游
|
||
git config --global push.autoSetupRemote true
|
||
|
||
# rebase 自动 stash
|
||
git config --global rebase.autoStash true
|
||
|
||
# 默认分支名
|
||
git config --global init.defaultBranch main
|
||
|
||
# 换行符处理
|
||
git config --global core.autocrlf input # Mac/Linux
|
||
git config --global core.autocrlf true # Windows
|
||
```
|
||
|
||
### 推荐工具
|
||
|
||
| 类型 | 工具 | 作用 |
|
||
|------|------|------|
|
||
| 提交检查 | husky + lint-staged | commit 前自动跑 lint/format |
|
||
| 提交规范 | commitlint | 强制 Conventional Commits |
|
||
| 密钥扫描 | gitleaks / git-secrets | 防止推送密钥 |
|
||
| 图形化客户端 | Fork / SourceTree / GitKraken | 新人友好 |
|
||
| CLI 增强 | gh / lazygit | 命令行高效操作 |
|
||
| CI/CD | GitHub Actions / GitLab CI | 自动测试和部署 |
|
||
| PR 预览 | Vercel / Netlify | 每 PR 一个独立环境 |
|
||
|
||
### 一键安装 husky + lint-staged + commitlint（Node 项目）
|
||
|
||
```bash
|
||
bun add -D husky lint-staged @commitlint/cli @commitlint/config-conventional
|
||
|
||
# 初始化 husky
|
||
bunx husky init
|
||
|
||
# 配置 commitlint
|
||
echo "export default { extends: ['@commitlint/config-conventional'] }" > commitlint.config.mjs
|
||
|
||
# 添加 hooks
|
||
echo "bunx commitlint --edit \$1" > .husky/commit-msg
|
||
echo "bunx lint-staged" > .husky/pre-commit
|
||
```
|
||
|
||
`package.json` 添加：
|
||
|
||
```json
|
||
{
|
||
"lint-staged": {
|
||
"*.{js,ts,tsx}": ["eslint --fix", "prettier --write"]
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 附录：决策速查表
|
||
|
||
### 我该开什么类型的分支？
|
||
|
||
| 我要做的事 | 分支前缀 | 例子 |
|
||
|----------|---------|------|
|
||
| 新功能 | `feature/` | `feature/评查详情页` |
|
||
| 修 bug | `fix/` | `fix/登录闪退` |
|
||
| 紧急修生产 | `hotfix/` | `hotfix/支付失败` |
|
||
| 重构 | `refactor/` | `refactor/数据层` |
|
||
| 写文档 | `docs/` | `docs/api文档` |
|
||
| 升级依赖 | `chore/` | `chore/升级react18` |
|
||
|
||
### 我该写什么 commit type？
|
||
|
||
| 我做了什么 | type |
|
||
|----------|------|
|
||
| 写了新功能 | `feat` |
|
||
| 修 bug | `fix` |
|
||
| 重构（不改行为） | `refactor` |
|
||
| 性能优化 | `perf` |
|
||
| 改文档 | `docs` |
|
||
| 改格式（空格、缩进） | `style` |
|
||
| 加测试 | `test` |
|
||
| 杂项 | `chore` |
|
||
|
||
### 我该用哪个工作流？
|
||
|
||
```
|
||
1 人 → 方案 A（main + 偶尔 feature）
|
||
2-5 人 → 方案 B（GitHub Flow，main + feature + PR）
|
||
6+ 人 / 多版本 → 方案 C（Git Flow Lite，main + develop + ...）
|
||
```
|
||
|
||
---
|
||
|
||
## 附录：一页纸速查（打印贴墙）
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────┐
|
||
│ 团队 Git 协作 · 一页纸速查 │
|
||
├─────────────────────────────────────────────────────────┤
|
||
│ 1. 永远从最新主干开任务分支 │
|
||
│ git checkout main && git pull --rebase │
|
||
│ git checkout -b feature/任务描述 │
|
||
│ │
|
||
│ 2. 分支命名 = 任务，不带人名！ │
|
||
│ ✅ feature/评查详情页 │
|
||
│ ❌ feature/评查详情页-zhangsan │
|
||
│ │
|
||
│ 3. commit 写人话 │
|
||
│ ✅ feat(评查): 新增详情页骨架 │
|
||
│ ❌ update │
|
||
│ │
|
||
│ 4. 推送前先同步 │
|
||
│ git fetch && git rebase origin/main │
|
||
│ │
|
||
│ 5. 主分支 = PR 入口，禁止直推 │
|
||
│ │
|
||
│ 6. 共享资源 = 通知 → 操作 → 还原 → 告知 │
|
||
│ │
|
||
│ 7. 永远不对 main/develop --force │
|
||
│ │
|
||
│ 8. 合并后立刻删分支 │
|
||
└─────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
---
|
||
|