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 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