git-surgeon

git-surgeon gives AI agents surgical control over git changes without interactive prompts. Stage, unstage, or discard individual hunks. Commit hunks directly with line-range precision. Restructure history by splitting commits or folding fixes into earlier ones.

Check out jj-hunk-tool if you're using Jujutsu.

Also from the author of git-surgeon: aven, one queue for every project, with a keyboard-driven TUI for you and a CLI for your agents.

Why?

AI agents can't use interactive git commands like git add -p. When asked to commit changes separately, they resort to destructive workarounds:

❯ commit the changes separately

⏺ Bash(git diff internal/bot/listing_handler.go)
  ⎿  diff --git i/internal/bot/listing_handler.go ...
     ... +83 lines

⏺ Let me reset and make the changes in two separate commits.

⏺ Bash(git checkout internal/bot/listing_handler.go)   ← about to destroy changes
  ⎿  Interrupted

With git-surgeon, the agent can inspect hunks and commit them selectively:

❯ commit the changes separately

⏺ I'll commit these as separate changes using git-surgeon.

⏺ Skill(git-surgeon)
  ⎿  Successfully loaded skill

⏺ Bash(git-surgeon hunks)
  ⎿  ac34353 internal/bot/listing_handler.go (+6 -3)
     15baf94 internal/bot/listing_handler.go (+10 -2)
     ...

⏺ Bash(git-surgeon commit ac34353 15baf94 7c6ef9e -m "allow edit commands during attribute input")

⏺ Bash(git-surgeon commit 4eefac8 bbba931 -m "add logging for attribute prompts")

What agents can do with git-surgeon

• Stage, unstage, or discard individual hunks by ID
• Commit selected hunks in one step
• Stage specific lines within a hunk, not just whole hunks (example)
• Split commits that mix concerns into focused commits (example), even retroactively (example)
• Fold existing commits into earlier commits (fold)
• Fold staged changes into earlier commits (amend)
• Squash, reword, and reorder commits
• Selectively undo hunks from previous commits
• Commit to another branch without checking it out

Quick start

1. Install

# Shell
curl -fsSL https://raw.githubusercontent.com/raine/git-surgeon/main/scripts/install.sh | bash

# Cargo
cargo install git-surgeon

# Homebrew
brew install raine/git-surgeon/git-surgeon

2. Install the agent skill

# Claude Code
git-surgeon install-skill --claude

# OpenCode
git-surgeon install-skill --opencode

# Codex
git-surgeon install-skill --codex

Alternatively, for Claude Code via the plugin marketplace:

claude plugin marketplace add raine/git-surgeon
claude plugin install git-surgeon@git-surgeon

3. Use it

Ask Claude Code to make granular commits. It will use git-surgeon automatically to stage individual hunks instead of entire files.

Commands

Command	Description
hunks	List hunks in the diff
show	Show full diff for a specific hunk
stage	Stage hunks by ID
commit	Stage hunks and commit in one step
commit-to	Commit hunks directly to another branch
unstage	Unstage hunks by ID
discard	Discard working tree changes for hunks
fold	Fold existing commits into an earlier commit
amend	Fold staged changes into an earlier commit
reword	Change the commit message of an existing commit
squash	Squash multiple commits into one
undo	Reverse-apply hunks from a commit
split	Split a commit into multiple commits by hunk selection
move	Move a commit to a different position in history
update	Update git-surgeon to the latest version

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>

---

hunks

Lists all hunks with their IDs, file paths, function context, change counts, and a preview of changed lines.

# List unstaged hunks
git-surgeon hunks

# List staged hunks
git-surgeon hunks --staged

# Filter to a specific file
git-surgeon hunks --file src/main.rs

# List hunks from a specific commit
git-surgeon hunks --commit HEAD
git-surgeon hunks --commit abc1234

# Show full diff with line numbers (useful for small commits)
git-surgeon hunks --commit abc1234 --full

# Show blame information for each line (which commit introduced it)
git-surgeon hunks --blame

Example output

a1b2c3d src/main.rs fn handle_request (+3 -1)
  -    let result = process(input);
  +    let result = match process(input) {
  +        Ok(v) => v,
  +        Err(e) => return Err(e),
  +    };

e4f5678 src/lib.rs (+1 -0)
  +use std::collections::HashMap;

Each line shows: <hunk-id> <file> [function context] (+additions -deletions)

Blamed output (--blame)

Use --blame to see which commit introduced each line:

a1b2c3d src/main.rs fn handle_request (+3 -1)
  8922b52  context line
  b538223 -deleted line
  0000000 +added line

• Context and removed lines show the 7-char hash of the commit that introduced them
• Added lines show 0000000 since they're uncommitted
• For --commit diffs, added lines show the commit hash instead

---

show

Shows the full diff (header + all lines) for a single hunk. Each line is prefixed with a 1-based line number for use with --lines.

git-surgeon show a1b2c3d

# Show a hunk from a specific commit
git-surgeon show a1b2c3d --commit HEAD

Example output

@@ -1,4 +1,6 @@ fn main
1: context
2:-deleted line
3:+added line
4: context

Searches both unstaged and staged diffs when no --commit is specified.

---

stage

Stages one or more hunks by ID. Equivalent to selectively answering "y" in git add -p.

git-surgeon stage a1b2c3d
git-surgeon stage a1b2c3d e4f5678

# Stage only lines 5-30 of a hunk
git-surgeon stage a1b2c3d --lines 5-30

---

commit

Stages hunks and commits them in a single step. Equivalent to running stage followed by git commit. If the commit fails, the hunks are unstaged to restore the original state. Refuses to run if the index already contains staged changes.

git-surgeon commit a1b2c3d e4f5678 -m "add pagination"

# With inline line ranges
git-surgeon commit a1b2c3d:1-11 e4f5678 -m "add pagination"

---

commit-to

Commits hunks directly to another branch without checking it out. Useful in worktree setups where you want to commit changes to a branch that is checked out in a different worktree.

git-surgeon commit-to main a1b2c3d e4f5678 -m "fix typo in shared util"

# With inline line ranges
git-surgeon commit-to main a1b2c3d:1-11 e4f5678 -m "fix typo"

The command applies the selected hunks to the target branch's tree using git plumbing (no checkout required), creates a commit, and discards those hunks from the working tree. Refuses to run if the target is the current branch or the index has staged changes.

If the patch cannot be applied cleanly to the target branch (e.g., the file has diverged), the command fails without modifying anything.

---

unstage

Unstages one or more previously staged hunks, moving them back to the working tree.

git-surgeon unstage a1b2c3d
git-surgeon unstage a1b2c3d e4f5678

# Unstage only lines 5-30 of a hunk
git-surgeon unstage a1b2c3d --lines 5-30

---

discard

Discards working tree changes for specific hunks. This reverse-applies the hunks, effectively running git checkout -p non-interactively.

git-surgeon discard a1b2c3d

# Discard only lines 5-30 of a hunk
git-surgeon discard a1b2c3d --lines 5-30

Warning: This permanently removes uncommitted changes for the specified hunks.

---

fold

Folds one or more existing commits into an earlier commit, removing the source commits from history and merging their changes into the target. Intermediate commits are preserved. By default, folds HEAD into the target.

For folding staged changes instead, use amend.

# Fold HEAD into an earlier commit
git-surgeon fold abc1234

# Fold a specific commit (not HEAD) into an earlier one
git-surgeon fold abc1234 --from def5678

# Fold multiple commits into one target in a single pass
git-surgeon fold abc1234 --from def5678 aaa1111 bbb2222

Multiple --from values are folded in a single rebase, avoiding repeated history rewrites and SHA tracking. Commits are applied in their original chronological order regardless of the order given on the command line.

Uses a rebase internally. If a conflict occurs, the repo is left in the conflict state for manual resolution (git rebase --continue or git rebase --abort). Dirty working tree is autostashed and restored. Refuses to run when the index already has staged changes.

---

amend

Folds currently staged changes into an earlier commit. Uses git commit --amend for HEAD, or an autosquash rebase for older commits. Unstaged changes are preserved via --autostash.

For folding an existing commit instead, use fold.

# Stage some hunks, then amend an earlier commit
git-surgeon stage a1b2c3d
git-surgeon amend abc1234

# Amend HEAD (equivalent to git commit --amend --no-edit)
git-surgeon amend HEAD

If the rebase hits a conflict, the repo is left in the conflict state for manual resolution (git rebase --continue or git rebase --abort).

---

reword

Changes the commit message of an existing commit without modifying its content. Uses git commit --amend for HEAD, or an autosquash rebase for older commits.

# With subject + body
git-surgeon reword HEAD -m "subject" -m "body paragraph"

# Change an earlier commit's message
git-surgeon reword abc1234 -m "corrected message"

If the rebase hits a conflict, the repo is left in the conflict state for manual resolution (git rebase --continue or git rebase --abort).

---

squash

Combines commits from <commit> through HEAD into a single commit.