Splitting a commit with jj

Mechanics for stack-split-commit in a Jujutsu checkout. Read SKILL.md first for the by-concern rule and the message handling, which hold whichever tool you use.

If the commit is to be split based on path

  1. Identify the commit to split - Use jj log to find the revision ID of the commit you want to split

  2. View the files in the commit - Use jj log -r –stat to see which files are in the commit

  3. Split the commit - Use jj split -r -m “description for first commit”

  • The -r flag specifies which revision to split

  • The -m flag sets the description for the commit with the selected files

  • The file path argument specifies which file(s) go in the first commit

  • All remaining files automatically go into a new commit on top

  1. Update the second commit’s description - Use jj describe -r -m “description for second commit” to set a proper description for the automatically created second commit

  2. Verify the split - Use jj log –stat to confirm each commit now contains only its respective file

Key points:

  • jj split with a fileset argument is non-interactive and deterministic (reliable)

  • The original commit keeps its position in history with the selected files

  • The remaining files go into a new commit automatically placed on top

  • Descendant commits are automatically rebased

If the commit is to be split based on hunks (split changes in the same file)

  1. Export the full diff jj show -r –git > /tmp/full.patch

  2. Manually split the patch into separate files

  • Open full.patch in an editor

  • Create hunk-1.patch containing only the required hunks

  • Create hunk-2.patch containing only the remaining hunks

  • Etc.

  • IMPORTANT: Store patches outside the repo (e.g., /tmp/) so they don’t disappear when switching revisions

  1. Go back to parent jj edit

  2. Apply each patch and make jj new -m “description of hunk 1” patch -p1 < /tmp/hunk-1.patch

jj new -m “description of hunk 2” patch -p1 < /tmp/hunk-2.patch

repeat as needed

  1. Abandon the original commit jj abandon

Advantages:

  • Preserves exact line numbers and context

  • Good for complex hunks with specific formatting

  • Can be partially automated with tools like splitpatch or filterdiff

  • Patch files serve as documentation of what was split

Key principles for reliable splitting

  1. Avoid interactive tools - They’re not scriptable or reproducible

  2. Store artifacts outside the repo - Patch files should be in /tmp/ or similar

  3. Verify each step - Use jj diff/jj show to confirm each commit contains only what you expect

  4. Clean up - Abandon the original multi-hunk commit when done