Git 工作流与版本管理

Git 是你的安全网。将提交视为存档点，将分支视为沙盒，将历史视为文档。

使用场景

始终适用。每一次代码变更都流经 git。

核心原则

基于主干的开发（推荐）

保持 main 始终可部署。在生命周期短暂的功能分支中工作，并在 1-3 天内合并回主干。

main ──●──●──●──●──●──●──●──●──●──  (always deployable)
        ╲      ╱  ╲    ╱
         ●──●─╱    ●──╱    ← short-lived feature branches (1-3 days)

• 开发分支是成本。 分支存活的每一天，都会累积合并风险。
• 功能开关 > 长期分支。 优先将未完成的工作部署在功能开关之后。

1. 尽早提交，频繁提交

每一次成功的增量都获得自己的提交。

Work pattern:
  Implement slice → Test → Verify → Commit → Next slice

Not this:
  Implement everything → Hope it works → Giant commit

2. 原子提交

每次提交只做一件逻辑上的事情：

# Good: Each commit is self-contained
git log --oneline
a1b2c3d Add task creation endpoint with validation
d4e5f6g Add task creation form component
h7i8j9k Connect form to API and add loading state
m1n2o3p Add task creation tests (unit + integration)

# Bad: Everything mixed together
x1y2z3a Add task feature, fix sidebar, update deps, refactor utils

3. 描述性的提交信息

提交信息解释为什么，而不仅仅是做了什么：

# Good: Explains intent
feat: add email validation to registration endpoint

Prevents invalid email formats from reaching the database.
Uses Zod schema validation at the route handler level.

# Bad: Describes what's obvious from the diff
update auth.ts

格式：

<type>: <short description>

<optional body explaining why, not what>

类型：

• feat —— 新功能
• fix —— Bug 修复
• refactor —— 既不修复 Bug 也不增加功能的代码变更
• test —— 新增或更新测试
• docs —— 仅文档变更
• chore —— 工具、依赖、配置

4. 关注点分离

不要将格式化变更与行为变更混在一起：

# Good: Separate concerns
git commit -m "refactor: extract validation logic to shared utility"
git commit -m "feat: add phone number validation to registration"

# Bad: Mixed concerns
git commit -m "refactor validation and add phone number field"

5. 控制变更规模

目标是每个提交/PR 约 100 行：

~100 lines  → Easy to review, easy to revert
~300 lines  → Acceptable for a single logical change
~1000 lines → Split into smaller changes

分支策略

功能分支

main (always deployable)
  │
  ├── feature/task-creation    ← One feature per branch
  ├── feature/user-settings    ← Parallel work
  └── fix/duplicate-tasks      ← Bug fixes

分支命名

feature/<short-description>   → feature/task-creation
fix/<short-description>       → fix/duplicate-tasks
chore/<short-description>     → chore/update-deps
refactor/<short-description>  → refactor/auth-module

存档点模式

Agent starts work
    │
    ├── Makes a change
    │   ├── Test passes? → Commit → Continue
    │   └── Test fails? → Revert to last commit → Investigate
    │
    └── Feature complete → All commits form a clean history

提交前的卫生检查

每次提交前：

# 1. Check what you're about to commit
git diff --staged

# 2. Ensure no secrets
git diff --staged | grep -i "password\|secret\|api_key\|token"

# 3. Run tests
npm test

# 4. Run linting
npm run lint

# 5. Run type checking
npx tsc --noEmit

使用 Git 进行调试

# Find which commit introduced a bug
git bisect start
git bisect bad HEAD
git bisect good <known-good-commit>

# View what changed recently
git log --oneline -20
git diff HEAD~5..HEAD -- src/

# Find who last changed a specific line
git blame src/services/task.ts

# Search commit messages for a keyword
git log --grep="validation" --oneline

验证

对每一次提交：

• [ ] 提交只做一件逻辑上的事情
• [ ] 提交信息解释了原因，并遵循类型约定
• [ ] 提交前测试通过
• [ ] diff 中没有密钥
• [ ] 没有将仅格式化的变更与行为变更混在一起
• [ ] .gitignore 覆盖了标准的排除项