git-surgeon
Install · Commands · Examples · Changelog
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.
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 fix commits into earlier commits (fixup/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 |
fixup | Fold a commit 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 |
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