git-workflow

Git 工作流

完整的 Git 工作流模式：GitHub Flow 分支管理、原子提交和恢复操作。对于维护整洁、便于审查的历史记录至关重要。

参数解析

SUBCOMMAND = "$ARGUMENTS[0]"  # Optional subcommand, e.g., "recovery", "branch", "stacked"
# If no arguments, show full workflow reference.
# $ARGUMENTS is the full string (CC 2.1.59 indexed access)

分支命名约定

# Feature branches (link to issue)
issue/<number>-<brief-description>
issue/123-add-user-auth

# When no issue exists
feature/<description>
fix/<description>
hotfix/<description>

分支规则：

1. main 始终可部署
2. 从 main 创建分支，并通过 PR 合并回 main
3. 分支存续时间 < 1-3 天
4. 合并后删除分支

---

原子提交检查清单

[ ] 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

交互式暂存

# Stage changes hunk-by-hunk
git add -p

# Options:
# y - stage this hunk
# n - skip this hunk
# s - split into smaller hunks
# e - manually edit the hunk
# q - quit

# Review what's staged
git diff --staged    # What will be committed
git diff             # What won't be committed

提交模式

# Separate concerns
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"
# GOOD: Two separate commits

---

快速恢复参考

安全网

# ALWAYS check reflog first - it has everything
git reflog

# Shows ALL recent HEAD movements
# Even "deleted" commits live here for 90 days

常见恢复场景

场景	尚未推送	已经推送
撤销提交	git reset --soft HEAD~1	git revert HEAD
分支错误	cherry-pick + reset	cherry-pick + revert
提交丢失	git reset --hard HEAD@{N}	不适用
rebase 出错	git rebase --abort 或 reflog	reflog + force-with-lease

快速恢复命令

# Undo last commit, keep changes staged
git reset --soft HEAD~1

# Find lost commits
git reflog | grep "your message"

# Recover to previous state
git reset --hard HEAD@{1}

# Safe force push (feature branches only)
git push --force-with-lease

---

标准工作流

# 1. Start fresh
git checkout main && git pull origin main
git checkout -b issue/123-my-feature

# 2. Work with atomic commits
git add -p
git commit -m "feat(#123): Add User model"

# 3. Stay updated
git fetch origin && git rebase origin/main

# 4. Push and PR
git push -u origin issue/123-my-feature
gh pr create --fill

# 5. Cleanup after merge
git checkout main && git pull
git branch -d issue/123-my-feature

---

反模式

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 创建分支 - 始终从干净状态开始
2. 交互式暂存 - 使用 git add -p
3. 每次提交只做一件事 - 如果描述里有“以及”，就拆分
4. 使用 rebase，而非 merge - 保持历史记录整洁
5. 先检查 reflog - 出现问题时先检查
6. 使用 force-with-lease - 比强制推送更安全
7. 合并后删除 - 不保留过时分支

相关技能

• ork:commit - 使用约定格式创建提交并进行提交前验证
• git-recovery - 使用 reflog 操作快速恢复常见 Git 错误
• stacked-prs - 为包含依赖 PR 的大型功能进行多 PR 开发
• ork:create-pr - 按规范格式全面创建 PR

关键决策

决策	选择	理由
分支模型	GitHub Flow	简单的单分支工作流，main 始终可部署
合并策略	优先 rebase，而非 merge	保持历史记录整洁且线性，更便于二分查找
分支命名	issue/-	将工作关联到跟踪项，并支持自动化
提交粒度	原子提交（每次只做一件事）	可独立撤销，历史记录清晰，也更便于审查
强制推送	仅使用 --force-with-lease	防止覆盖共享分支上其他人的工作

规则

每个类别都在 rules/ 中设有独立规则文件，按需加载：

类别	规则	影响	关键模式
分支保护	${CLAUDE_PLUGIN_ROOT}/skills/git-workflow/rules/branch-protection.md	CRITICAL	受保护分支，必须遵循 PR 工作流
合并策略	${CLAUDE_PLUGIN_ROOT}/skills/git-workflow/rules/merge-strategy.md	HIGH	优先 rebase、冲突解决、force-with-lease
历史记录清理	${CLAUDE_PLUGIN_ROOT}/skills/git-workflow/rules/history-hygiene.md	HIGH	压缩 WIP、fixup 提交、整洁的历史记录
恢复	${CLAUDE_PLUGIN_ROOT}/skills/git-workflow/rules/recovery-reflog.md	CRITICAL	使用 reflog 恢复丢失的提交和分支
恢复	${CLAUDE_PLUGIN_ROOT}/skills/git-workflow/rules/recovery-reset.md	CRITICAL	安全与危险的 reset 模式
恢复	${CLAUDE_PLUGIN_ROOT}/skills/git-workflow/rules/recovery-stash.md	HIGH	stash 管理和已丢弃 stash 的恢复
堆叠 PR	${CLAUDE_PLUGIN_ROOT}/skills/git-workflow/rules/stacked-pr-workflow.md	HIGH	堆叠规划、PR 创建、依赖关系跟踪
堆叠 PR	${CLAUDE_PLUGIN_ROOT}/skills/git-workflow/rules/stacked-pr-rebase.md	HIGH	rebase 管理、force-with-lease、调整目标分支
单体仓库	${CLAUDE_PLUGIN_ROOT}/skills/git-workflow/rules/monorepo-context.md	MEDIUM	--add-dir、各服务的 CLAUDE.md、工作区检测

共计：6 个类别中的 9 条规则

参考资料

按需使用 Read("${CLAUDE_PLUGIN_ROOT}/skills/git-workflow/references/<file>") 加载：

文件	内容
github-flow.md	GitHub Flow 分支指南
interactive-staging.md	交互式暂存模式
reflog-recovery.md	Reflog 恢复技巧
recovery-decision-tree.md	恢复场景决策树

检查清单

按需使用 Read("${CLAUDE_PLUGIN_ROOT}/skills/git-workflow/checklists/<file>") 加载：

文件	内容
branch-checklist.md	创建分支前的检查
pre-commit-checklist.md	提交前的验证