git-workflow

Git 工作流与最佳实践

目的

全面介绍 git 操作的指南，重点关注整洁的历史记录、原子化提交和专业的工作流。自动分析暂存的更改并贯彻单一职责原则。

适用场景

执行任何 git 操作时启用：

• 提交更改（尤其是涉及多个文件时）
• 创建分支
• 合并或变基
• 管理 git 历史记录
• 编写提交消息
• 整理暂存区
• 准备代码审查
• 管理代码仓库

核心理念

单一职责规则 ⭐

重要： 提交之前，分析暂存的更改，并将其拆分为原子化提交。

流程：

1. 运行 git status 查看所有已暂存文件
2. 识别不同的关注点／功能
3. 取消暂存所有内容：git reset HEAD
4. 按关注点分组暂存文件，每次处理一组
5. 为每组提交编写聚焦的消息
6. 重复以上步骤，直到提交完所有更改

原因： 让历史记录更易于审查、撤销和维护。

⛔ 提交前的强制检查

问问自己：“如果明天我只需要撤销其中一项更改，能做到吗？”

• 不能 → 存在多个关注点 → 必须拆分为多个独立提交
• 能 → 可以进行单个提交

常见误区：“所有文件都与同一项功能需求有关”并不是打包提交的正当理由。每项可以独立撤销的更改都应单独提交。

---

提交组织

分析暂存的更改

# Check what's staged
git status

# See file-level summary
git diff --cached --stat

# See detailed changes
git diff --cached

# Check specific file
git diff --cached path/to/file

分组策略

按功能分组：

• 身份验证系统的更改 → 一个提交
• 支付模块 → 单独一个提交
• 用户个人资料 → 再单独一个提交

按层分组：

• 数据库迁移 → 第一个提交
• 后端 API → 第二个提交
• 前端 UI → 第三个提交
• 测试 → 第四个提交

按类型分组：

• 新功能（feat）
• Bug 修复（fix）
• 重构（refactor）
• 文档（docs）
• 性能优化（perf）
• 测试（test）

按依赖关系分组：

• 先提交基础／基础设施
• 再提交依赖这些基础的功能

拆分工作流

# 1. Analyze current state
git status
git diff --cached --stat

# 2. Unstage everything
git reset HEAD

# 3. Stage first logical group
git add file1.ts file2.ts directory/

# 4. Verify what's staged
git diff --cached --stat

# 5. Commit with focused message
git commit -m "type: concise description"

# 6. Repeat steps 3-5 for remaining groups

示例：实际场景

情况： 暂存了 29 个文件，涉及多个关注点

# Before - messy staging
$ git status
Changes to be committed:
  # Trading Styles feature (25 files)
  modified:   src/app/styles/page.tsx
  new file:   src/core/domain/models/TradingStyle.ts
  new file:   src/infrastructure/database/migrations/create_trading_styles.ts
  ...
  # History enhancements (4 files)
  modified:   src/app/history/page.tsx
  modified:   src/app/api/history/recommendations/route.ts
  ...

解决方案：

# 1. Reset staging
git reset HEAD

# 2. Commit #1 - Trading Styles feature
git add \
  package.json pnpm-lock.yaml \
  src/app/styles/ \
  src/core/domain/models/TradingStyle.ts \
  src/core/ports/ITradingStyleRepository.ts \
  src/infrastructure/database/TradingStyleRepository.ts \
  src/infrastructure/database/migrations/create_trading_styles.ts

git commit -m "feat: Add trading style persona system for AI-powered analysis"

# 3. Commit #2 - History enhancements
git add \
  src/app/history/page.tsx \
  src/app/api/history/recommendations/route.ts \
  src/infrastructure/database/TimeseriesRepository.ts \
  src/components/layout/AppLayout.tsx

git commit -m "feat: Add comprehensive search and filtering to history page"

结果： 提交内容整洁、聚焦，可独立审查和撤销。

---

提交消息

Conventional Commits 格式

<type>(<scope>): <subject>

<body>

<footer>

类型

• feat - 新功能
• fix - Bug 修复
• refactor - 代码重构（不改变行为）
• perf - 性能优化
• docs - 仅文档更改
• style - 格式、空白字符、分号
• test - 添加／更新测试
• chore - 维护、依赖项
• build - 构建系统更改
• ci - CI/CD 配置
• revert - 撤销之前的提交

主题行规则

• 使用祈使语气：“Add feature”，而不是“Added feature”
• 以小写字母开头（首字母不要大写）
• 末尾不加句号
• 最多 50 个字符
• 描述具体明确

正文指南

• 说明是什么更改以及为什么更改，而不是如何实现
• 每行最多 72 个字符
• 有多项更改时使用项目符号
• 引用问题编号：Fixes #123
• 说明破坏性更改

示例

良好示例：

git commit -m "$(cat <<'EOF'
feat: add trading style filtering to history page

Implemented comprehensive search and filtering:
- Multi-criteria filtering (action, type, risk, style)
- Partial symbol search with case-insensitive matching
- LEFT JOIN with trading_styles table
- Extended API with new query parameters

Fixes #456
EOF
)"

不良示例：

git commit -m "Fixed stuff"
git commit -m "WIP"
git commit -m "Updated files"

---

分支策略

分支命名

格式： type/description-in-kebab-case

类型：

• feature/ - 新功能
• fix/ - Bug 修复
• refactor/ - 代码改进
• docs/ - 文档
• test/ - 添加测试
• chore/ - 维护

示例：

feature/trading-style-personas
fix/history-filter-bug
refactor/database-queries
docs/api-documentation

分支工作流

# Create and switch to new branch
git checkout -b feature/new-feature

# Work on changes
git add ...
git commit -m "..."

# Keep branch updated with main
git fetch origin
git rebase origin/main

# Push to remote
git push origin feature/new-feature

# Create pull request (via GitHub/GitLab UI)

分支管理

# List all branches
git branch -a

# Switch branches
git checkout branch-name

# Delete local branch
git branch -d branch-name

# Delete remote branch
git push origin --delete branch-name

# Rename current branch
git branch -m new-name

---

暂存操作

选择性暂存

# Stage specific files
git add file1.ts file2.ts

# Stage entire directory
git add src/features/

# Stage all changes
git add .

# Stage by file extension
git add *.ts

# Interactive staging (patch mode)
git add -p file.ts

补丁模式操作

使用 git add -p 时：

• y - 暂存此区块
• n - 不暂存此区块
• s - 拆分为更小的区块
• e - 手动编辑区块
• q - 退出
• ? - 帮助

取消暂存

# Unstage all files
git reset HEAD

# Unstage specific file
git restore --staged file.ts

# Unstage directory
git restore --staged src/features/

---

历史记录管理

查看历史记录

# Compact history
git log --oneline -10

# Detailed history
git log -5

# With file changes
git log --stat -3

# Specific file history
git log -- path/to/file

# Graph view
git log --oneline --graph --all

# Search commits
git log --grep="search term"

# By author
git log --author="name"

# Date range
git log --since="2 weeks ago"

修改提交

# Add forgotten files to last commit
git add forgotten-file.ts
git commit --amend --no-edit

# Change last commit message
git commit --amend -m "new message"

⚠️ 警告： 只能修改尚未推送的提交！

交互式变基

# Rebase last 3 commits
git rebase -i HEAD~3

# Rebase from specific commit
git rebase -i commit-hash

选项：

• pick - 保留提交原样
• reword - 更改提交消息
• edit - 修改提交
• squash - 与前一个提交合并
• fixup - 类似 squash，但丢弃提交消息
• drop - 移除提交

压缩提交

推送之前：

# Squash last 3 commits
git rebase -i HEAD~3
# Mark commits as "squash" or "fixup"

挑选提交

# Apply specific commit to current branch
git cherry-pick commit-hash

# Cherry-pick multiple commits
git cherry-pick hash1 hash2 hash3

---

合并与变基

合并与变基的区别

合并：

• 创建合并提交
• 保留完整历史记录
• 用于：将功能分支集成到 main

git checkout main
git merge feature/new-feature

变基：

• 重写历史记录，形成线性时间线
• 历史记录更整洁
• 用于：用 main 的更改更新功能分支

git checkout feature/new-feature
git rebase main

合并策略

快进（默认）：

git merge feature/branch

非快进（始终创建合并提交）：

git merge --no-ff feature/branch

压缩（合并所有提交）：

git merge --squash feature/branch
git commit -m "feat: merged feature"

解决冲突

# Check conflict status
git status

# View conflicts
git diff

# After resolving conflicts in editor
git add resolved-file.ts

# Continue rebase
git rebase --continue

# Or abort
git rebase --abort

---

远程操作

使用远程仓库

# View remotes
git remote -v

# Add remote
git remote add origin https://github.com/user/repo.git

# Update remote URL
git remote set-url origin new-url

# Fetch from remote
git fetch origin

# Pull with rebase
git pull --rebase origin main

# Push to remote
git push origin branch-name

# Force push (use carefully!)
git push --force-with-lease origin branch-name

拉取请求工作流

# 1. Update local main
git checkout main
git pull origin main

# 2. Create feature branch
git checkout -b feature/new-feature

# 3. Make changes and commit atomically
# (following single-responsibility rule)

# 4. Keep branch updated
git fetch origin
git rebase origin/main

# 5. Push to remote
git push origin feature/new-feature

# 6. Create PR via GitHub/GitLab UI

# 7. Address review feedback
git add .
git commit -m "fix: address review comments"
git push origin feature/new-feature

# 8. After PR merged, clean up
git checkout main
git pull origin main
git branch -d feature/new-feature

---

高级技巧

暂存

# Stash current changes
git stash

# Stash with message
git stash save "work in progress"

# List stashes
git stash list

# Apply last stash
git stash apply

# Apply and remove stash
git stash pop

# Apply specific stash
git stash apply stash@{2}

# Drop stash
git stash drop stash@{0}

# Clear all stashes
git stash clear

打标签

# Create lightweight tag
git tag v1.0.0

# Create annotated tag
git tag -a v1.0.0 -m "Release version 1.0.0"

# List tags
git tag

# Push tag to remote
git push origin v1.0.0

# Push all tags
git push origin --tags

# Delete tag
git tag -d v1.0.0
git push origin --delete v1.0.0

二分查找（查找 Bug）

# Start bisect
git bisect start

# Mark current commit as bad
git bisect bad

# Mark known good commit
git bisect good commit-hash

# Git will checkout middle commit
# Test it, then mark as good or bad
git bisect good  # or git bisect bad

# Repeat until bug is found
# Reset after finding
git bisect reset

Reflog（恢复）

# View reflog
git reflog

# Recover lost commit
git reset --hard commit-hash

# Recover deleted branch
git checkout -b recovered-branch commit-hash

---

Git 忽略规则

.gitignore 模式

# Ignore file
secret.env

# Ignore directory
node_modules/

# Ignore by extension
*.log

# Ignore except specific file
!important.log

# Ignore in all subdirectories
**/debug.log

常见忽略项

# Dependencies
node_modules/
vendor/

# Build outputs
dist/
build/
*.exe

# Environment
.env
.env.local

# IDE
.vscode/
.idea/
*.swp

# OS
.DS_Store
Thumbs.db

# Logs
*.log
logs/

---

最佳实践检查清单

提交之前

• 运行 git status 分析已暂存的文件
• ⛔ GATE：“我能否独立地仅还原一项更改？”如果不能 → 拆分提交
• 按单一职责对更改分组
• 取消暂存无关文件
• 仅将相关文件一起暂存
• 提交前检查 git diff --cached
• 编写清晰、具体的提交消息
• 遵循 Conventional Commits 格式
• 确保代码构建成功
• 适用时运行测试
• 确认提交可独立审查

分支管理

• 使用描述性分支名称
• 缩短分支的存续时间
• 定期与 main 变基
• 删除已合并的分支
• 不要直接提交到 main

提交质量

• 原子提交（每个提交只涉及一项关注点）
• 有意义的提交消息
• 不使用 WIP 或“修复一些东西”之类的消息
• 提交中不包含已注释掉的代码
• 不包含生成的文件（除非必要）
• 不包含秘密或凭据

代码审查

• 拉取请求小而聚焦
• PR 标题和描述具有说明性
• 引用相关问题
• 请求审查前先自行审查
• 处理所有审查意见
• 审查期间保持提交整洁

---

应避免的反模式

❌ 巨型混合提交

git add .
git commit -m "various changes"

问题： 无法审查、还原或理解

解决方法： 按关注点拆分为原子提交

❌ “相关”内容打包提交

# Multiple features bundled because "they're all for the same task"
git add src/components/Form.tsx src/components/PDFExport.tsx src/types/ src/config/
git commit -m "feat: add form and PDF export with new field types"

问题：“与同一请求相关”≠“属于同一提交”。还原 PDF 时无法避免 Form 也一并丢失。

测试： 你能否独立还原其中一项功能？不能？那就拆分。

解决方法：

git add src/config/ src/types/
git commit -m "feat: add field mapping configuration"

git add src/components/Form.tsx
git commit -m "feat: add editable form component"

git add src/components/PDFExport.tsx
git commit -m "feat: add PDF export with bank-style layout"

❌ 直接提交到 Main

git checkout main
git commit -m "quick fix"
git push

问题： 绕过代码审查，风险较高

解决方法： 始终使用功能分支

❌ 强制推送到共享分支

git push --force origin main

问题： 破坏他人的工作，扰乱历史记录

解决方法： 使用 --force-with-lease，且仅用于自己的分支

❌ 大型二进制文件

git add large-video.mp4
git commit -m "add video"

问题： 永久增大仓库体积

解决方法： 使用 Git LFS 或外部存储

❌ 提交秘密

git add .env
git commit -m "add config"

问题： 存在安全漏洞，且难以移除

解决方法： 使用 .gitignore、环境变量和秘密管理工具

❌ 毫无意义的消息

git commit -m "fix"
git commit -m "update"
git commit -m "wip"

问题： 历史记录无法用于调试

解决方法： 编写描述清晰、内容具体的提交消息

---

快速参考

必备命令

# Status and diff
git status
git diff
git diff --cached
git diff --stat

# Staging
git add file.ts
git add .
git reset HEAD
git restore --staged file.ts

# Committing
git commit -m "message"
git commit --amend

# Branching
git branch
git checkout -b branch-name
git branch -d branch-name

# History
git log --oneline -10
git log --stat
git show commit-hash

# Remote
git fetch origin
git pull --rebase
git push origin branch-name

# Stashing
git stash
git stash pop

恢复命令

# Undo last commit (keep changes)
git reset --soft HEAD~1

# Undo last commit (discard changes)
git reset --hard HEAD~1

# Undo changes to file
git restore file.ts

# Recover deleted branch
git reflog
git checkout -b branch-name commit-hash

---

资源

• Conventional Commits： https://www.conventionalcommits.org/
• Git Book： https://git-scm.com/book/en/v2
• Oh Shit, Git!： https://ohshitgit.com/

---

状态：可用于生产环境 ✅ 行数：约 480 行（低于 500 行规则）✅ 覆盖范围：完整的 Git 工作流 + 原子提交执行 ✅