git-surgeon

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