Back to Details

git-workflow

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Git Workflow

Git工作流

Complete git workflow patterns: GitHub Flow branching, atomic commits, and recovery operations. Essential for maintaining clean, reviewable history.
完整的Git工作流模式：GitHub Flow分支管理、原子提交以及恢复操作。是保持提交记录整洁、便于评审的核心指南。

Branch Naming Convention

分支命名规范

bash
undefined
bash
undefined

Feature branches (link to issue)

功能分支（关联议题）

issue/<number>-<brief-description> issue/123-add-user-auth
issue/<编号>-<简要描述> issue/123-add-user-auth

When no issue exists

无对应议题时

feature/<description> fix/<description> hotfix/<description>

**Branch Rules:**
1. `main` is always deployable
2. Branch from `main`, PR back to `main`
3. Branches live < 1-3 days
4. Delete branch after merge

---
feature/<描述> fix/<描述> hotfix/<描述>

**分支规则：**
1. `main`分支始终处于可部署状态
2. 从`main`分支创建新分支，合并请求（PR）提交回`main`
3. 分支生命周期不超过1-3天
4. 合并后删除分支

---

Atomic Commit Checklist

原子提交检查清单

[ ] Does ONE logical thing
[ ] Leaves codebase working (tests pass)
[ ] Message doesn't need "and" in title
[ ] Can be reverted independently
[ ] Title < 50 chars, body wraps at 72
[ ] 仅包含一个逻辑单元的变更
[ ] 提交后代码库可正常运行（测试通过）
[ ] 提交信息标题中无需使用“和”连接内容
[ ] 可独立回滚
[ ] 标题不超过50字符，正文每行不超过72字符

Interactive Staging

交互式暂存

bash
undefined
bash
undefined

Stage changes hunk-by-hunk

分块暂存变更

git add -p
git add -p

Options:

选项说明：

y - stage this hunk

y - 暂存当前块

n - skip this hunk

n - 跳过当前块

s - split into smaller hunks

s - 将当前块拆分为更小的块

e - manually edit the hunk

e - 手动编辑当前块

q - quit

q - 退出

Review what's staged

查看已暂存内容

git diff --staged # What will be committed git diff # What won't be committed
undefined
git diff --staged # 即将提交的内容 git diff # 未暂存的内容
undefined

Commit Patterns

提交模式

bash
undefined
bash
undefined

Separate concerns

分离关注点

git add -p && git commit -m "refactor: Extract database pool" git add -p && git commit -m "feat(#456): Add query caching"
git add -p && git commit -m "refactor: Extract database pool" git add -p && git commit -m "feat(#456): Add query caching"

Never combine unrelated changes

切勿合并不相关的变更

BAD: "feat: Add auth and fix formatting"

错误示例： "feat: Add auth and fix formatting"

GOOD: Two separate commits

正确做法：拆分为两个独立提交


---

---

Recovery Quick Reference

快速恢复参考

The Safety Net

安全保障：Reflog

bash
undefined
bash
undefined

ALWAYS check reflog first - it has everything

遇到问题先查看reflog - 它记录了所有操作

git reflog
git reflog

Shows ALL recent HEAD movements

显示所有最近的HEAD移动记录

Even "deleted" commits live here for 90 days

即使是“已删除”的提交也会在此保留90天

undefined
undefined

Common Recovery Scenarios

常见恢复场景

ScenarioNot PushedAlready Pushed
Undo commit
git reset --soft HEAD~1
git revert HEAD
Wrong branchcherry-pick + resetcherry-pick + revert
Lost commits
git reset --hard HEAD@{N}
N/A
Bad rebase
git rebase --abort
or reflog		reflog + force-with-lease
场景未推送到远程已推送到远程
撤销提交
git reset --soft HEAD~1
git revert HEAD
提交到错误分支cherry-pick + resetcherry-pick + revert
找回丢失的提交
git reset --hard HEAD@{N}
不适用
错误变基
git rebase --abort
或查看reflog		reflog + force-with-lease

Quick Recovery Commands

快速恢复命令

bash
undefined
bash
undefined

Undo last commit, keep changes staged

撤销最后一次提交，保留已暂存的变更

git reset --soft HEAD~1
git reset --soft HEAD~1

Find lost commits

查找丢失的提交

git reflog | grep "your message"
git reflog | grep "你的提交信息"

Recover to previous state

恢复到之前的状态

git reset --hard HEAD@{1}
git reset --hard HEAD@{1}

Safe force push (feature branches only)

安全强制推送（仅用于功能分支）

git push --force-with-lease

---
git push --force-with-lease

---

Standard Workflow

标准工作流

bash
undefined
bash
undefined

1. Start fresh

1. 拉取最新代码

git checkout main && git pull origin main git checkout -b issue/123-my-feature
git checkout main && git pull origin main git checkout -b issue/123-my-feature

2. Work with atomic commits

2. 进行原子提交

git add -p git commit -m "feat(#123): Add User model"
git add -p git commit -m "feat(#123): Add User model"

3. Stay updated

3. 保持代码同步

git fetch origin && git rebase origin/main
git fetch origin && git rebase origin/main

4. Push and PR

4. 推送并创建PR

git push -u origin issue/123-my-feature gh pr create --fill
git push -u origin issue/123-my-feature gh pr create --fill

5. Cleanup after merge

5. 合并后清理

git checkout main && git pull git branch -d issue/123-my-feature

---
git checkout main && git pull git branch -d issue/123-my-feature

---

Anti-Patterns

反模式（需避免）

Avoid:
- Long-lived branches (> 1 week)
- Merging main into feature (use rebase)
- Direct commits to main
- Force push to shared branches
- Commits that need "and" in message
- Committing broken code
避免以下做法：
- 长期存在的分支（超过1周）
- 将main分支合并到功能分支（应使用变基）
- 直接提交到main分支
- 对共享分支执行强制推送
- 提交信息标题中包含“和”的内容
- 提交无法运行的代码

Best Practices Summary

最佳实践总结

  1. Branch from main - Always start fresh
  2. Stage interactively - Use 
    git add -p
  3. One thing per commit - If you say "and", split it
  4. Rebase, don't merge - Keep history clean
  5. Check reflog first - When something goes wrong
  6. Force-with-lease - Safer than force push
  7. Delete after merge - No stale branches
  1. 从main分支创建新分支 - 始终基于最新代码开始工作
  2. 使用交互式暂存 - 采用
    git add -p
    命令
  3. 每次提交仅做一件事 - 如果需要用“和”描述，就拆分提交
  4. 使用变基而非合并 - 保持提交记录整洁线性
  5. 遇到问题先查reflog - 这是恢复的首选方式
  6. 使用--force-with-lease进行强制推送 - 比普通force push更安全
  7. 合并后删除分支 - 避免遗留 stale分支

Related Skills

相关技能

  • ork:commit
    - Create commits with conventional format and pre-commit validation
  • git-recovery
    - Quick recovery from common git mistakes using reflog operations
  • stacked-prs
    - Multi-PR development for large features with dependent PRs
  • ork:create-pr
    - Comprehensive PR creation with proper formatting
  • ork:commit
    - 按照约定格式创建提交，并进行预提交验证
  • git-recovery
    - 使用reflog操作快速恢复常见Git错误
  • stacked-prs
    - 针对大型功能的多PR开发，处理依赖PR
  • ork:create-pr
    - 创建格式规范的完整PR

Key Decisions

核心决策

DecisionChoiceRationale
Branching modelGitHub FlowSimple single-branch workflow, main is always deployable
Merge strategyRebase over mergeKeeps history clean and linear, easier to bisect
Branch namingissue/<number>-<desc>Links work to tracking, enables automation
Commit granularityAtomic (one thing)Independent revert, clear history, easier review
Force push--force-with-lease onlyPrevents overwriting others' work on shared branches
决策选择理由
分支模型GitHub Flow简单的单分支工作流，main始终可部署
合并策略优先变基而非合并保持提交记录整洁线性，便于二分查找问题
分支命名issue/<编号>-<描述>关联工作追踪系统，支持自动化操作
提交粒度原子化（仅一件事）可独立回滚，提交记录清晰，便于评审
强制推送仅使用--force-with-lease防止覆盖共享分支上他人的工作

Rules

规则

Each category has individual rule files in 
rules/
loaded on-demand:
CategoryRuleImpactKey Pattern
Branch Protection
rules/branch-protection.md
CRITICALProtected branches, required PR workflow
Merge Strategy
rules/merge-strategy.md
HIGHRebase-first, conflict resolution, force-with-lease
History Hygiene
rules/history-hygiene.md
HIGHSquash WIP, fixup commits, clean history
Recovery
rules/recovery-reflog.md
CRITICALReflog recovery for lost commits and branches
Recovery
rules/recovery-reset.md
CRITICALSafe vs dangerous reset modes
Recovery
rules/recovery-stash.md
HIGHStash management and dropped stash recovery
Stacked PRs
rules/stacked-pr-workflow.md
HIGHStack planning, PR creation, dependency tracking
Stacked PRs
rules/stacked-pr-rebase.md
HIGHRebase management, force-with-lease, retargeting
Monorepo
rules/monorepo-context.md
MEDIUM--add-dir, per-service CLAUDE.md, workspace detection
Total: 9 rules across 6 categories
每个分类的独立规则文件位于
rules/
目录，按需加载：
分类规则影响等级核心模式
分支保护
rules/branch-protection.md
关键受保护分支，强制PR工作流
合并策略
rules/merge-strategy.md
高优先变基，冲突解决，force-with-lease
提交记录整洁性
rules/history-hygiene.md
高压缩WIP提交，fixup提交，保持记录整洁
恢复操作
rules/recovery-reflog.md
关键使用Reflog恢复丢失的提交和分支
恢复操作
rules/recovery-reset.md
关键安全与危险的reset模式区分
恢复操作
rules/recovery-stash.md
高Stash管理及丢失stash的恢复
堆叠PR
rules/stacked-pr-workflow.md
高堆叠规划，PR创建，依赖追踪
堆叠PR
rules/stacked-pr-rebase.md
高变基管理，force-with-lease，重新定向
单体仓库
rules/monorepo-context.md
中--add-dir，按服务的CLAUDE.md，工作区检测
总计：6个分类下的9条规则

References

参考资料

  • GitHub Flow Guide
  • Interactive Staging
  • Reflog Recovery
  • Recovery Decision Tree
  • GitHub Flow Guide
  • Interactive Staging
  • Reflog Recovery
  • Recovery Decision Tree

Checklists

检查清单

  • Branch Checklist - Pre-flight checks before creating branches
  • Pre-Commit Checklist - Validation before committing
  • Branch Checklist - 创建分支前的预检查清单
  • Pre-Commit Checklist - 提交前的验证清单