/git-surgeon

name: git-surgeon
description: Non-interactive hunk-level git staging, unstaging, discarding, undoing, fold, amend, squash, commit splitting, and commit reordering. Use when selectively staging, unstaging, discarding, reverting, squashing, splitting, or reordering individual diff hunks by ID instead of interactively.

git-surgeon

CLI for hunk-level git operations without interactive prompts. Useful for AI agents that need precise control over which changes to stage, unstage, discard, or undo.

Commands

# List unstaged hunks (shows ID, file, +/- counts, preview)
git-surgeon hunks

# List staged hunks
git-surgeon hunks --staged

# Filter to one file
git-surgeon hunks --file=src/main.rs

# List hunks from a specific commit
git-surgeon hunks --commit <HEAD/sha>

# Show all hunks with line numbers (for small commits needing line-range splits)
git-surgeon hunks --commit <sha> --full

# Show blame info (which commit introduced each line)
git-surgeon hunks --blame
git-surgeon hunks --blame --staged
git-surgeon hunks --blame --commit <sha>

# Show full diff for a hunk (lines are numbered for use with --lines)
git-surgeon show <id>
git-surgeon show <id> --commit HEAD

# Stage specific hunks
git-surgeon stage <id1> <id2> ...

# Stage only part of a hunk by line range
git-surgeon stage <id> --lines 5-30

# Stage and commit hunks in one step
git-surgeon commit <id1> <id2> ... -m "message"

# With inline line ranges
git-surgeon commit <id>:1-11 <id2> -m "message"

# Commit hunks directly to another branch (no checkout needed)
git-surgeon commit-to <branch> <id1> <id2> ... -m "message"
git-surgeon commit-to main <id>:1-11 <id2> -m "message"

# Unstage specific hunks
git-surgeon unstage <id1> <id2> ...
git-surgeon unstage <id> --lines 5-30

# Discard working tree changes for specific hunks
git-surgeon discard <id1> <id2> ...
git-surgeon discard <id> --lines 5-30

# Fold existing commits into an earlier commit (default: HEAD into target)
git-surgeon fold <target>
git-surgeon fold <target> --from <commit>
git-surgeon fold <target> --from <commit1> <commit2> <commit3>

# Fold staged changes into an earlier commit
git-surgeon amend <commit>

# Change commit message
git-surgeon reword HEAD -m "new message"
git-surgeon reword <commit> -m "new message"
git-surgeon reword HEAD -m "subject" -m "body"

# Squash ALL commits from <commit> through HEAD into one
git-surgeon squash HEAD~1 -m "combined feature"
git-surgeon squash HEAD~2 -m "Add user auth" -m "Implements JWT-based authentication."
git-surgeon squash <commit> -m "feature complete"
git-surgeon squash HEAD~3 --force -m "squash with merges"
git-surgeon squash HEAD~1 --no-preserve-author -m "use current author"

# Undo specific hunks from a commit (reverse-apply to working tree)
git-surgeon undo <id1> <id2> ... --from <commit>
git-surgeon undo <id> --from <commit> --lines 2-10

# Undo all changes to specific files from a commit
git-surgeon undo-file <file1> <file2> ... --from <commit>

# Split a commit into multiple commits by hunk selection
git-surgeon split HEAD \
  --pick <id1> <id2> -m "first commit" \
  --rest-message "remaining changes"

# Split with subject + body (multiple -m flags, like git commit)
git-surgeon split HEAD \
  --pick <id1> -m "Add feature" -m "Detailed description here." \
  --rest-message "Other changes" --rest-message "Body for rest."

# Split with line ranges (comma syntax or repeat ID for non-contiguous ranges)
git-surgeon split <commit> \
  --pick <id>:1-11,20-30 <id2> -m "partial split"

# Move a commit after another commit
git-surgeon move <sha> --after <target-sha>

# Move a commit before another commit
git-surgeon move <sha> --before <target-sha>

# Move a commit to the end of the branch
git-surgeon move <sha> --to-end

# Update git-surgeon to the latest version
git-surgeon update

# Split into three+ commits
git-surgeon split HEAD \
  --pick <id1> -m "first" \
  --pick <id2> -m "second" \
  --rest-message "rest"

Typical workflow

1. Run `git-surgeon hunks` to list hunks with their IDs 2. Use `git-surgeon show <id>` to inspect a hunk (lines are numbered) 3. Stage and commit in one step: `git-surgeon commit <id1> <id2> -m "message"` 4. Or stage separately: `git-surgeon stage <id1> <id2>`, then `git commit` 5. To commit only part of a hunk, use inline ranges: `git-surgeon commit <id>:5-30 -m "message"`

Committing to another branch

Use `commit-to` when working in a worktree and you need to commit changes to a branch checked out elsewhere (e.g., main):

1. Run `git-surgeon hunks` to list hunks 2. Commit to another branch: `git-surgeon commit-to main <id1> <id2> -m "message"` 3. The hunks are applied to the target branch's tree and discarded from the working tree 4. Fails if the patch cannot be applied cleanly to the target branch

Picking the right folding command

| You have... | Use | | ---------------------------------------- | ---------------------------------------- | | Staged changes | `git-surgeon amend <target>` | | One existing commit, defaulting to HEAD | `git-surgeon fold <target>` | | One or more named commits | `git-surgeon fold <target> --from <sha>` |

Folding existing commits into earlier commits

`fold` folds one or more existing commits into an earlier one. The source(s) (default: HEAD) are removed from history and their changes merge into the target. Intermediate commits stay untouched. Dirty working tree is autostashed. Refuses to run when the index already has staged changes.

• `git-surgeon fold <target>` -- fold HEAD into target (most common)
• `git-surgeon fold <target> --from <commit>` -- fold a specific non-HEAD commit
• `git-surgeon fold <target> --from <c1> <c2> <c3>` -- fold multiple commits in one pass
• Fails if the range contains merge commits

Using --blame to find the fold target

Use `--blame` to see which commit introd