一、用一个真实案例串起来（重点看流程）

场景设定

• 仓库：zlxydl/backend-api
• 分支：main（保护分支，禁止直接 push）
• 成员：你（Alice）、同事（Bob）
• 目标：Alice 开发「链路追踪」功能

✅ Step 1：初始化本地环境（只需一次）

git clone https://github.com/zlxydl/backend-api.git
cd backend-api

git config user.name "Alice"
git config user.email "alice@example.com"

✅ Step 2：基于最新 main 建功能分支

git checkout main
git pull origin main
git checkout -b feature/trace-link

📌 规范约定

分支命名：feature/xxx、fix/xxx、hotfix/xxx

✅ Step 3：开发 & 提交（多次）

# 修改代码
git add .
git commit -m "feat(trace): 添加链路追踪基础结构"

📌 Commit Message 规范（见下文）

✅ Step 4：Bob 抢先合入了 main（冲突来源）

Bob 提交了：

fix(log): 优化日志格式

此时你的本地 main 已经落后。

✅ Step 5：同步远程 main（关键步骤）

git checkout main
git pull --rebase origin main

✅ Step 6：变基你的功能分支（避免无意义 merge）

git checkout feature/trace-link
git rebase main

如果出现冲突：

# 打开冲突文件，手动解决
git add <冲突文件>
git rebase --continue

📌 永远不在 main 上 rebase 别人的提交

✅ Step 7：推送功能分支

git push origin feature/trace-link

✅ Step 8：提 PR（Pull Request）

• 目标分支：main
• 标题：feat(trace): 添加链路追踪支持
• 描述：做了什么 / 影响范围 / 测试方式
• 指定 Reviewer

✅ Step 9：Code Review 通过后合并

推荐方式：

• ✅ Squash and merge（保持 main 干净）
• ❌ 不用 Merge pull request（历史太乱）

二、团队协作 Git 规范模板（直接复制用）

📄 GIT_WORKFLOW.md（放在仓库根目录）

# Git 协作规范

## 分支模型
- main：生产分支（保护，禁止直接 push）
- feature/*：功能开发
- fix/*：Bug 修复
- hotfix/*：线上紧急修复

## 日常流程
1. 拉取最新 main
2. 新建功能分支
3. 开发 & 提交
4. 定期 rebase main
5. 提 PR
6. Code Review
7. Squash merge

## Commit Message 规范
<type>(<scope>): <subject>

type:
- feat：新功能
- fix：修复 bug
- docs：文档
- style：格式
- refactor：重构
- test：测试
- chore：构建/工具

示例：
feat(trace): 添加链路追踪模块
fix(log): 修复日志丢失问题
docs(readme): 更新部署说明

📄 .gitconfig（推荐配置）

[user]
    name = Your Name
    email = your@email.com

[core]
    autocrlf = input
    editor = code --wait

[pull]
    rebase = true

[alias]
    co = checkout
    br = branch
    ci = commit
    st = status
    lg = log --oneline --graph --decorate --all
    up = !git fetch origin && git rebase origin/main
    save = !git add . && git commit -m 'WIP: savepoint'
    undo = reset --soft HEAD~1

[merge]
    ff = only

安装方式：

git config --global include.path ~/.gitconfig

📄 .gitignore（通用版）

# OS
.DS_Store
Thumbs.db

# IDE
.idea/
.vscode/
*.swp

# Node
node_modules/
dist/

# Go
bin/
*.exe
*.test

# Logs
*.log

# Env
.env

三、团队“铁律”（一定要贴在墙上）

✅ main 分支永远是可发布状态
✅ 一个功能一个分支
✅ Commit 前先拉最新 main 并 rebase
✅ 已 push 的提交，禁止 rebase
✅ PR 至少一人 Review 才能合并
✅ 禁止 git push -f 到 main

四、你之前的问题，在这套规范里的答案

push 时发现 main 变了怎么办？

✅ 你不该直接 push main ✅ 正确做法：

git checkout main
git pull --rebase origin main
git checkout feature/xxx
git rebase main
git push origin feature/xxx