sanurb/jj-hunk

jj-hunk: Programmatic Hunk Selection

Use jj-hunk for non-interactive hunk selection in jj. Essential for AI agents that need to create clean, logical commits from mixed changes.

When to Use This Skill

• Splitting a commit into multiple logical commits
• Committing only specific hunks (partial commit)
• Squashing only certain changes into parent
• Any hunk selection that would normally require jj split -i or jj squash -i

Setup

cargo install jj-hunk

Add to ~/.jjconfig.toml:

[merge-tools.jj-hunk]
program = "jj-hunk"
edit-args = ["select", "$left", "$right"]

Core Workflow

1. List Hunks

jj-hunk list              # working copy (@)
jj-hunk list -r <rev>     # any revision

Output (JSON):

{
  "src/foo.rs": [
    {"index": 0, "type": "replace", "removed": "old\n", "added": "new\n"},
    {"index": 1, "type": "insert", "removed": "", "added": "// added\n"}
  ],
  "src/bar.rs": [
    {"index": 0, "type": "delete", "removed": "removed\n", "added": ""}
  ]
}

2. Build a Spec

Select hunks by index or use file-level actions:

{
  "files": {
    "src/foo.rs": {"hunks": [0]},
    "src/bar.rs": {"action": "keep"},
    "src/baz.rs": {"action": "reset"}
  },
  "default": "reset"
}

| Spec | Effect | |------|--------| | {"hunks": [0, 2]} | Include only hunks 0 and 2 | | {"action": "keep"} | Include all changes | | {"action": "reset"} | Discard all changes | | "default": "reset" | Unlisted files are discarded | | "default": "keep" | Unlisted files are kept |

3. Execute

# Split: selected hunks → first commit, rest → second commit
jj-hunk split '<spec>' "commit message"
jj-hunk split -r <rev> '<spec>' "commit message"  # split any revision

# Commit: selected hunks committed, rest stays in working copy
jj-hunk commit '<spec>' "commit message"

# Squash: selected hunks squashed into parent
jj-hunk squash '<spec>'
jj-hunk squash -r <rev> '<spec>'  # squash any revision into its parent

Examples

Split Mixed Changes into Logical Commits

You have refactoring and a new feature mixed together:

# 1. See what hunks exist
jj-hunk list

# 2. Split out the refactoring first
jj-hunk split '{"files": {"src/lib.rs": {"hunks": [0, 1]}}, "default": "reset"}' \
  "refactor: extract helper function"

# 3. Remaining changes become second commit
jj describe -m "feat: add new feature"

Commit Only Part of Your Changes

Keep experimental code in working copy while committing the fix:

jj-hunk commit '{"files": {"src/bug.rs": {"action": "keep"}}, "default": "reset"}' \
  "fix: handle null case"

Squash Specific Files into Parent

jj-hunk squash '{"files": {"src/tests.rs": {"action": "keep"}}, "default": "reset"}'

Keep Everything Except One File

jj-hunk split '{"files": {"src/wip.rs": {"action": "reset"}}, "default": "keep"}' \
  "feat: complete implementation"

Split a Non-Working-Copy Revision

# List hunks in a specific revision
jj-hunk list -r urx

# Split it — examples go to first commit, rest stays
jj-hunk split -r urx \
  '{"files": {"examples/README.md": {"action": "keep"}}, "default": "reset"}' \
  "examples of extensions"

Direct jj --tool Usage

The commands above are wrappers. For direct control:

# Write spec to file
echo '{"files": {"src/foo.rs": {"hunks": [0]}}, "default": "reset"}' > /tmp/spec.json

# Run jj with the tool
JJ_HUNK_SELECTION=/tmp/spec.json jj split -i --tool=jj-hunk -m "message"

Hunk Types

| Type | Meaning | |------|---------| | insert | New lines added | | delete | Lines removed | | replace | Lines changed (removed + added) |

Tips

• Always list first: Run jj-hunk list to see hunk indices before building specs
• Use default wisely: "default": "reset" is safer (explicit inclusion), "default": "keep" is convenient for excluding specific files
• Combine with jj: After splitting, use jj describe to refine commit messages