
git-hex
Git history rewrite and conflict-resolution tools (MCP) with curated skills.
Install
/plugin install git-hex@git-hex-marketplaceRun it inside Claude Code after adding the marketplace with /plugin marketplace add yaniv-golan/git-hex.
Contents
Discovered from sourceSkills 3
Git-hex Branch Cleanup
Use this skill when the user wants to reshape a feature branch's commit history using git-hex tools instead of manual interactive rebase.
Workflow
1. Assess the situation
- Call
git-hex-getRebasePlanto see the commit range.- Use
countto control how far back (default 10, max 200). - Commits come back oldest-first — the natural order for a rebase plan.
- If
ontois omitted it defaults to@{upstream}orHEAD~count.
- Use
- Optionally call
git-hex-checkRebaseConflictsto predict conflicts before starting. This requires git 2.40+ — if the user's git is older, skip it and note the limitation.
2. Choose the right tool for the job
| Goal | Tool | Notes |
|---|---|---|
| Edit the last commit (message or content) | amendLastCommit | Use addAll: true to stage tracked changes automatically. Needs at least staged changes OR a new message. |
| Fix an older commit | createFixup → rebaseWithPlan | User must stage changes first. Then createFixup targets the commit; follow with rebaseWithPlan using autosquash: true to fold it in. |
| Reorder, drop, squash, or reword | rebaseWithPlan | Pass a plan array. For reordering, set requireComplete: true. |
| Break a commit into focused pieces | splitCommit | Requires splits array with ≥2 entries. Every file in the original commit must appear in exactly one split. |
| Cherry-pick a single commit | cherryPickSingle | Rejects merge commits. Use abortOnConflict: false to pause on conflicts instead of aborting. |
3. Execute safely
- Prefer
autoStash: truewhen the working tree is dirty.rebaseWithPlanuses git's native--autostash.amendLastCommituses--keep-indexmode (preserves staged changes).splitCommitandcherryPickSingleuse git-hex's own stash helper.
- Never rewrite shared or protected branches — only feature branches the user controls.
- All write operations create backup refs automatically.
4. Handle stash restore failures
Tools that manage their own stash (amendLastCommit, splitCommit,
cherryPickSingle) return stashNotRestored: true if the stash pop fails
after the operation succeeds. When you see this:
- Tell the user their operation succeeded but their stashed changes couldn't be reapplied cleanly.
- Suggest running
git stash listto find the stash entry, thengit stash popmanually to resolve any conflicts.
rebaseWithPlan uses git's native --autostash and does not emit this flag —
git handles it internally.
5. Recover from mistakes
- Call
git-hex-undoLastto restore the state before the last git-hex operation. - It requires a clean working tree. Use
force: trueonly if commits were added after the backup or untracked files would be overwritten. - If a rebase pauses with conflicts, hand off to the git-hex-conflict-resolution skill.
Gotchas
rewordrequiresmessage— without it, git opens an editor and hangs.- Messages must be single-line — no TAB or newline characters in
messagefields forreword,splitCommit, orcreateFixup. createFixupneeds staged changes — it doesn't stage anything itself. Remind the user togit addfirst.requireComplete: true— when reordering, every commit in the range must appear in the plan. Without this, unmentioned commits default topick.- Prefer
fixupoversquashunless the user wants to combine commit messages (squash opens an editor-like message merge; fixup silently discards). - Root commits can't be split —
splitCommitrejects them. - Merge commits can't be split or cherry-picked — both tools reject them.
- Detached HEAD —
getRebasePlanandrebaseWithPlanwarn about this in their summary. Flag it to the user if unexpected.
Git-hex Conflict Resolution
Use this skill when a git-hex operation is paused due to conflicts — or when the user reports being stuck in a rebase, merge, cherry-pick, or revert.
Workflow
1. Inspect the conflict state
Call git-hex-getConflictStatus to determine:
- Whether an operation is in progress and what type (
rebase,merge,cherry-pick,revert) - Which files are conflicting and the conflict type per file
- For rebases:
currentStep/totalStepsprogress
When to use includeContent: true:
- When you need to see the actual base/ours/theirs content to propose a resolution — typically for text files where you'll edit and resolve.
- Skip it for binary files (they'll be flagged
isBinary: true) or when you just need to see the list of conflicting files. - Use
maxContentSize(default 10000) to limit large files. Content is truncated per-file and marked withtruncated: true.
Important: inConflict: true can persist even after all files are resolved
if the operation is still paused. Check conflictingFiles length, not just
inConflict.
2. Resolve each conflicting file
For text files (both_modified, added_by_both):
- Read the conflict content (base/ours/theirs) from the
getConflictStatusresponse or by reading the file directly. - Edit the file to produce the correct merged content. Remove all conflict
markers —
resolveConflictwithresolution: "keep"will reject the file if any<<<<<<<,=======,>>>>>>>, or|||||||markers remain. - Call
git-hex-resolveConflictwithfileandresolution: "keep".
For delete conflicts (deleted_by_us, deleted_by_them):
resolution: "keep"— restores the file (from theirs if deleted_by_us, from ours if deleted_by_them).resolution: "delete"— accepts the deletion.- Ask the user which they prefer if the intent isn't clear.
Path rules: The file parameter must be a POSIX repo-relative path. No
absolute paths, no ../ traversal, no drive letters.
After each resolution, resolveConflict returns remainingConflicts — the
count of files still in conflict.
3. Continue or abort
Continue — when all conflicts are resolved (remainingConflicts: 0) or
getConflictStatus shows no remaining conflicting files:
- Call
git-hex-continueOperation. - It may return
paused: trueagain if the next commit in a rebase also conflicts. Go back to step 1 in that case. - Supports: rebase, cherry-pick, merge. Does not support revert or bisect —
for those, suggest
git revert --continue/git bisect resetdirectly.
Abort — if the user wants to abandon the operation:
- Call
git-hex-abortOperation. This restores the pre-operation state. - For a rebase initiated by git-hex,
git-hex-undoLastis also available as recovery after the operation completes (if the result wasn't what the user wanted).
4. Verify the result
After continueOperation reports completed: true, confirm the state:
- Use
git-hex-getRebasePlanorgit logto show the user the final history. - If the result isn't right, suggest
git-hex-undoLastto roll back.
Conflict types reference
Operation-level
| Type | Meaning |
|---|---|
rebase | Interactive rebase paused mid-apply |
merge | Merge in progress |
cherry-pick | Cherry-pick paused |
revert | Revert paused (limited tool support — see above) |
File-level
| Type | Meaning | Typical resolution |
|---|---|---|
both_modified | Both sides changed the file | Edit to merge, then keep |
deleted_by_us | We deleted, they modified | keep (restore) or delete |
deleted_by_them | We modified, they deleted | keep (restore) or delete |
added_by_both | Both sides added different versions | Edit to merge, then keep |
Git-hex PR Workflow
Use this skill when the user wants to go from a messy feature branch to a clean, submitted (or updated) pull request. This skill combines git-hex for local commit shaping with GitHub tools or CLI for remote collaboration.
Workflow
Phase 1: Understand the branch
- Call
git-hex-getRebasePlanwithontoset to the target branch (usuallymainororigin/main) to see all commits that will be in the PR. - Call
git-hex-checkRebaseConflictswith the sameontoto predict whether rebasing will be smooth. If conflicts are predicted, warn the user before proceeding — they may want to resolve upstream changes first.
Phase 2: Shape the history
Use the git-hex-branch-cleanup skill techniques to craft a clean, logical commit sequence. Common PR prep patterns:
- Squash WIP commits: Use
rebaseWithPlanwithfixupactions to collapse work-in-progress into meaningful commits. - Separate concerns: Use
splitCommitto break a large commit into focused, reviewable pieces (e.g., separate refactoring from feature work). - Reword for clarity: Use
rebaseWithPlanwithrewordactions to write commit messages that tell the PR's story. - Rebase onto latest main: Use
rebaseWithPlanwithonto: "origin/main"and an empty plan to fast-forward the base.
Phase 3: Push and create the PR
-
Push:
git push --force-with-lease(safe force push — refuses if the remote has commits you haven't seen).- For first push:
git push -u origin <branch>. - Never force-push to main/master.
- For first push:
-
Create or update the PR:
- Use
gh pr create(or the GitHub plugin if installed). - Craft the PR description from the commit history: Use the commits from
getRebasePlanto build a summary. Each well-crafted commit message becomes a bullet point or section in the PR body.
gh pr create --title "Short title" --body "$(cat <<'EOF' ## Summary - First logical change (from commit 1 message) - Second logical change (from commit 2 message) ## Test plan - [ ] Verify X - [ ] Check Y EOF )" - Use
Phase 4: Address review feedback
When the user gets review comments and wants to update the PR:
- Make the fix — edit the code as needed.
- Target the right commit — use
git-hex-createFixuppointing at the commit the review comment refers to. This keeps the fix associated with the original change. - Fold it in —
git-hex-rebaseWithPlanwithautosquash: trueto absorb the fixup commit. - Push again —
git push --force-with-lease.
This produces a clean history where each commit is correct, rather than a trail of "fix review comment" commits.
Phase 5: Handle stacked PRs (advanced)
When working with dependent branches:
- Rebase child branches after parent is rebased:
git-hex-rebaseWithPlanwithontoset to the rebased parent. - Use
git-hex-checkRebaseConflictsto preview whether the child rebase will conflict. - Push each branch with
--force-with-lease.
Tools to prefer
- Local craft: All git-hex tools (see branch-cleanup skill for details)
- Remote: GitHub plugin tools if installed; otherwise
ghCLI
Key insight
git-hex handles the local craft — shaping commits into a clean, reviewable story. GitHub tools handle the remote collaboration — creating PRs, adding reviewers, responding to comments. Together they cover the full PR lifecycle.
Gotchas
- Always fetch before rebasing onto main:
git fetch originfirst, then useorigin/mainas theontotarget. --force-with-leasenot--force: The lease check prevents overwriting teammates' pushes.- Review feedback fixups need staging:
createFixuprequires staged changes — remind the user togit addthe fix first. - PR description gets stale after rebase: If you rewrote history, update the PR description to match the new commits.
MCP servers 1
Sponsors
Details
- Marketplace
- yaniv-golan/git-hex
- Category
- Community