git-workflow

Git 工作流

将此技能用作本仓库本地协作与恢复的路由优先锚点。

它的目的不是讲解 Git 的所有内容，而是：

• 快速识别当前本地 Git 状态；
• 选择一种安全的工作流模式；
• 推荐能解决问题且改动最小、可撤销的修复方案；
• 明确划分审查、调试、规划和托管 PR 工作流的边界。

遇到棘手情况，或用户需要比简要说明更详细的指导时，请阅读以下参考资料：

• references/collaboration-boundaries.md
• references/mode-selection-and-command-packets.md
• references/recovery-patterns.md

如果主要需求是：

• 审查差异的正确性、架构或安全性 → 转到 code-review
• 复现或诊断 Bug／回归问题 → 转到 debugging
• 规划任务、验收标准或冲刺任务切片 → 转到 task-planning
• 运用基于 Aider 的 AI 结对编程编辑循环 → 转到 aider-cli-workflow
• 托管 PR 生命周期、分支保护、审查者、标签或仓库设置 → 使用专门的 PR／仓库管理工作流

何时使用此技能

• 在编码或审查前创建、重命名或清理分支
• 有选择地暂存更改，并整理出便于审查的提交
• 决定是合并还是变基到更新后的基分支
• 安全地解决合并／变基冲突
• 推送分支、设置上游，或使用 --force-with-lease 更新改写后的历史记录
• 从错误的重置、错误分支上的提交、分离的 HEAD、丢失的提交或混乱的变基中恢复
• 为后续 PR 或审查步骤准备干净的差异

何时不使用此技能

• 真正的问题是代码或架构是否优秀
• 真正的问题是如何拆分或安排工作顺序
• 真正的问题是根本原因，而非 Git 操作
• 真正的问题是托管服务工作流，而非本地仓库状态
• 用户想要的是一份冗长的 Git 教程，而非下一步安全操作

指令

步骤 1：规范化本地 Git 信息

在建议命令前先对请求分类。

git_intake:
  current_goal: branch-setup | commit-shaping | sync-with-base | conflict-resolution | push-safety | undo-recovery | history-inspection | unknown
  branch_state: clean | has-unstaged-changes | staged-only | ahead-of-origin | behind-origin | diverged | detached-head | unknown
  collaboration_risk: solo-branch | shared-branch | unknown
  remote_context: no-remote | origin-only | fork-plus-upstream | unknown
  trigger_event:
    - need-clean-commits
    - rebased-branch
    - merge-conflict
    - wrong-branch-commit
    - accidental-reset
    - rejected-push
    - lost-commit
    - prepare-for-review
    - sync-main
    - unclear
  preferred_history: keep-linear | preserve-merge-context | unknown
  confidence: high | medium | low

如果信息不完整，请选择最安全合理的下一步，并说明所依据的假设。

步骤 2：选择一种主要工作流模式

恰好选择一种模式：

1. 分支与暂存规范 — 创建／切换分支、暂存，以及决定暂存还是清理
2. 整理提交 — amend、fixup、reword、交互式变基，以及整理出更清晰的审查单元
3. 与基分支同步 — 分支需要追上进度时，在 fetch 后选择合并或变基
4. 解决冲突 — 合并／变基已产生冲突；此时最重要的是安全地完成后续操作
5. 安全推送 — 设置上游、处理推送被拒、分支分叉，以及安全推送改写后的历史记录
6. 撤销与恢复 — reset／rebase／amend／checkout／删除分支出了问题；先进行抢救

步骤 3：遵循安全阶梯

执行不可逆操作前，务必优先进行以下检查：

• git status
• git branch --show-current
• git log --oneline --decorate -5

核心规则：

• 提交边界很重要时，优先使用 git add -p 或明确指定要暂存的内容。
• 仅当历史记录位于本地或可以安全改写时，才优先使用 amend 或交互式变基。
• 分支主要由你维护，且更清晰的审查历史有帮助时，优先使用变基。
• 分支由多人共享，或保留集成上下文比线性历史更重要时，优先使用合并。
• 有意改写历史记录后，优先使用 git push --force-with-lease，绝不要直接使用 --force。
• 错误提交已共享时，优先使用 git revert，而不是 reset --hard。
• 慌乱清理前，优先检查 git reflog 并创建抢救分支。

步骤 4：应用决策阶梯

明确使用以下提示：

合并还是变基

• 使用变基：改写风险较低，且需要便于审查的线性历史时。
• 使用合并：分支由多人共享、集成上下文很重要，或改写风险不值得承担时。

revert 与 reset 的区别

• 对于已推送的历史记录，协作撤销时使用 revert。
• 只有在有意重写本地历史记录时才使用 reset。
• 如果需要修复工作区／索引，而不是分支历史记录，请使用 restore / checkout 文件。

普通推送与 --force-with-lease

• 如果没有重写历史记录，请使用普通推送。
• 在 rebase、amend、squash 或其他有意重写之后，使用 --force-with-lease。
• 如果分支可能由多人共享，且远程状态不明确，请暂停操作并说明协作风险。

步骤 5：编写 Git 工作流简报

按以下确切结构返回：

# Git Workflow Brief

## Recommended mode
- Mode: branch-and-stage hygiene | commit-shaping | sync-with-base | conflict-resolution | push-safety | undo-and-recovery
- Why this mode fits: ...

## Current state
- Branch: ...
- Worktree / index state: ...
- Remote context: ...
- Collaboration risk: solo-branch | shared-branch | unknown
- Confidence: high | medium | low

## Safest next move
1. ...
2. ...
3. ...

## Commands
```bash
...

为什么这是安全的做法

• ...
• ...

注意事项

• ...
• ...

恢复备用方案

• 如果出现问题，请使用 ...

后续衔接

• 在……情况下使用 code-review……
• 在……情况下使用 debugging……
• 在……情况下使用 task-planning……

### Step 6: Use concise mode packets
- **branch-and-stage hygiene** — branch name, dirty/clean state, selective staging, stash only when it lowers risk
- **commit-shaping** — reviewable commit units, amend/fixup/rebase only when rewrite is safe
- **sync-with-base** — fetch first, decide merge vs rebase explicitly, name rewrite risk before starting
- **conflict-resolution** — inspect → resolve → `git add` → continue/commit, with `abort` as the calm fallback
- **push-safety** — distinguish upstream creation, normal push, rejected push, and rewritten-history push
- **undo-and-recovery** — identify what moved, inspect `reflog`, create a rescue branch, prefer reversible steps first

Use the detailed command packets in [references/mode-selection-and-command-packets.md](references/mode-selection-and-command-packets.md) when you need the expanded workflow.

### Step 7: Keep boundaries sharp
Before finalizing:
- Do **not** turn this into a hosted PR tutorial.
- Do **not** pretend every branch should be rebased.
- Do **not** recommend `reset --hard` casually without naming the data-loss risk.
- Do **not** hide the solo-vs-shared branch distinction.
- Do **not** drift into code-review judgment, root-cause analysis, or backlog design.

## Output format
Always return a compact **Git Workflow Brief**, not a giant command dump.

Required qualities:
- choose one mode
- state the collaboration risk
- prefer the safest reversible path that solves the current problem
- make rewrite risk explicit
- include a recovery fallback when the commands have teeth
- keep routing boundaries to review, debugging, planning, and hosted PR workflows visible

## Examples

### Example 1: rebased branch needs safe push
**Input**
> I rebased my feature branch onto main and now I need to push it without overwriting teammates.

**Output sketch**
- Mode: `push-safety`
- State whether the branch looks solo or shared
- Recommend `git push --force-with-lease origin <branch>` only if rewrite is expected
- Watch-out warns against raw `--force`

### Example 2: clean up local commits before review
**Input**
> Help me turn these messy local commits into something clean before review.

**Output sketch**
- Mode: `commit-shaping`
- Suggest explicit staging plus `git rebase -i` or `git commit --amend`
- Keep the goal focused on reviewable commit units, not review comments themselves

### Example 3: wrong-branch reset panic
**Input**
> I think I hard-reset the wrong branch. Can Git recover this?

**Output sketch**
- Mode: `undo-and-recovery`
- Start with `git reflog`
- Create a rescue branch from the pre-reset SHA before further cleanup
- Explain when to stop and avoid more destructive commands

### Example 4: request is really PR review
**Input**
> Review this PR and tell me if the architecture is okay.

**Output sketch**
- Route away from `git-workflow`
- Explain that local Git prep is not the main problem here
- Hand off to `code-review`

## Best practices
1. **Inspect before surgery.** Status, branch, and recent log beat guesswork.
2. **Prefer reviewable commits over giant snapshots.** Commit shape affects review quality.
3. **Treat history rewrites as collaboration decisions, not personal preferences.** Shared branches change the answer.
4. **Use `--force-with-lease`, not raw `--force`.** Rewrite safely or do not rewrite.
5. **Reach for `reflog` early in recovery.** Lost commits are often only misplaced pointers.
6. **Choose the smallest safe fix.** Not every problem needs branch surgery.
7. **Route out when the problem changes.** Review, debugging, planning, and hosted PR work stay separate.

## References
- [references/collaboration-boundaries.md](references/collaboration-boundaries.md)
- [references/mode-selection-and-command-packets.md](references/mode-selection-and-command-packets.md)
- [references/recovery-patterns.md](references/recovery-patterns.md)
- Git documentation — https://git-scm.com/docs
- GitHub Docs, *Resolving merge conflicts after a Git rebase* — https://docs.github.com/en/get-started/using-git/resolving-merge-conflicts-after-a-git-rebase
- GitLab Docs, *Resolve conflicts from the command line* — https://docs.gitlab.com/topics/git/git_rebase/#resolve-conflicts-from-the-command-line