Git-hex Branch Cleanup
When to use this Skill
This skill should be used when:
- The user says they want to "clean up", "rewrite", "polish", or "squash" a git
history or feature branch.
- The user wants to rebase a branch onto another branch (e.g.
main) and present
a clean, reviewable set of commits.
- The user wants to split, squash, or reword commits using git-hex tools instead
of manual interactive rebase.
Trigger phrases include: "clean up my commits", "squash fixups", "polish history",
"rewrite commits", "rebase onto main", "make this branch reviewable".
Workflow
Plan first
- Call
git-hex-getRebasePlan to inspect the commit range you would modify.
- Optionally call
git-hex-checkRebaseConflicts to estimate whether the rebase
is likely to conflict.
Prepare changes
- For small edits to the last commit, prefer
git-hex-amendLastCommit.
- For fixes to older commits, guide the user to edit and stage changes, then
use
git-hex-createFixup targeting the original commit.
- For large or mixed commits, consider
git-hex-splitCommit to separate files
into focused commits.
Apply the rewrite
- Use
git-hex-rebaseWithPlan to reorder, drop, squash, or reword commits.
- Prefer
autoStash: true and autosquash: true when the working tree is dirty,
following git-hex documentation.
- Never use git-hex on shared or protected branches; operate on feature branches
the user controls.
Safety and recovery
- If the result is not what the user wanted, call
git-hex-undoLast to restore
the previous state using git-hex backup refs.
- If a rebase pauses with conflicts, hand off to the conflict resolution Skill.
Tools to prefer
- Planning:
git-hex-getRebasePlan, git-hex-checkRebaseConflicts
- History rewrite:
git-hex-rebaseWithPlan, git-hex-createFixup,
git-hex-amendLastCommit, git-hex-splitCommit, git-hex-cherryPickSingle
- Recovery:
git-hex-undoLast
Key constraints
reword action requires message field (without it, git opens an editor → hang).- Messages must be single-line (no TAB/newline characters).
- For reordering commits, set
requireComplete: true in the plan.
- Prefer
fixup over squash unless you need to combine commit messages.
- Tools that perform their own auto-stash (
amendLastCommit, splitCommit, cherryPickSingle) expose stashNotRestored when stash pop failed; rebaseWithPlan uses Git's native --autostash and does not emit this flag.
1---2name: git-hex-branch-cleanup3description: This skill should be used when the user wants to clean up a feature branch's history using git-hex (squash/fixup commits, reorder/drop/split commits, or rebase a branch onto main) without using an interactive terminal. Trigger phrases include: "clean up my branch", "polish history", "squash these commits", "fixup commits", "rebase onto main", "rewrite commits".4---5
6# Git-hex Branch Cleanup
7
8## When to use this Skill
9
10This skill should be used when:
11
12- The user says they want to "clean up", "rewrite", "polish", or "squash" a git
13 history or feature branch.
14- The user wants to rebase a branch onto another branch (e.g. `main`) and present
15 a clean, reviewable set of commits.
16- The user wants to split, squash, or reword commits using git-hex tools instead
17 of manual interactive rebase.
18
19Trigger phrases include: "clean up my commits", "squash fixups", "polish history",
20"rewrite commits", "rebase onto main", "make this branch reviewable".
21
22## Workflow
23
241. **Plan first**
25 - Call `git-hex-getRebasePlan` to inspect the commit range you would modify.
26 - Optionally call `git-hex-checkRebaseConflicts` to estimate whether the rebase
27 is likely to conflict.
28
292. **Prepare changes**
30 - For small edits to the last commit, prefer `git-hex-amendLastCommit`.
31 - For fixes to older commits, guide the user to edit and stage changes, then
32 use `git-hex-createFixup` targeting the original commit.
33 - For large or mixed commits, consider `git-hex-splitCommit` to separate files
34 into focused commits.
35
363. **Apply the rewrite**
37 - Use `git-hex-rebaseWithPlan` to reorder, drop, squash, or reword commits.
38 - Prefer `autoStash: true` and `autosquash: true` when the working tree is dirty,
39 following git-hex documentation.
40 - Never use git-hex on shared or protected branches; operate on feature branches
41 the user controls.
42
434. **Safety and recovery**
44 - If the result is not what the user wanted, call `git-hex-undoLast` to restore
45 the previous state using git-hex backup refs.
46 - If a rebase pauses with conflicts, hand off to the conflict resolution Skill.
47
48## Tools to prefer
49
50- Planning: `git-hex-getRebasePlan`, `git-hex-checkRebaseConflicts`
51- History rewrite: `git-hex-rebaseWithPlan`, `git-hex-createFixup`,
52 `git-hex-amendLastCommit`, `git-hex-splitCommit`, `git-hex-cherryPickSingle`
53- Recovery: `git-hex-undoLast`
54
55## Key constraints
56
57- `reword` action **requires** `message` field (without it, git opens an editor → hang).
58- Messages must be **single-line** (no TAB/newline characters).
59- For reordering commits, set `requireComplete: true` in the plan.
60- Prefer `fixup` over `squash` unless you need to combine commit messages.
61- Tools that perform their own auto-stash (`amendLastCommit`, `splitCommit`, `cherryPickSingle`) expose `stashNotRestored` when stash pop failed; `rebaseWithPlan` uses Git's native `--autostash` and does not emit this flag.
majiayu000