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"

Cherry-pick

# 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 检查暂存文件
• 按单一职责对变更分组
• 取消暂存无关文件
• 仅将相关文件一起暂存
• 提交前检查 git diff --cached
• 编写清晰、描述准确的提交信息
• 遵循 Conventional Commits 格式
• 确保代码可以成功构建
• 适用时运行测试
• 确认提交可以独立审查

分支管理

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

提交质量

• 原子提交（每个提交只涉及一个事项）
• 有意义的提交信息
• 不使用 WIP 或“修修补补”之类的信息
• 提交中不包含注释掉的代码
• 不包含生成文件（除非必要）
• 不包含机密或凭据

代码审查

• 创建小型、聚焦的拉取请求
• 编写描述清晰的 PR 标题和说明
• 引用相关问题
• 请求审查前先自行审查
• 处理所有审查意见
• 审查期间保持提交整洁

---

应避免的反模式

❌ 混杂大量内容的巨型提交

git add .
git commit -m "various changes"

问题： 无法审查、撤销或理解

解决方法： 按事项拆分为原子提交

❌ 直接提交到 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 工作流 + 原子提交规范 ✅