Source code
Revision control
Copy as Markdown
Other Tools
# 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 <revision> --stat to see which files are in the
commit
3. Split the commit - Use jj split -r <revision> -m "description for first commit" <first-file-path>
- 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
4. Update the second commit's description - Use jj describe -r <new-revision-id> -m "description for
second commit" to set a proper description for the automatically created second commit
5. 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 <changeid> --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
3. Go back to parent
jj edit <parent-revision-id>
4. 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
5. Abandon the original commit
jj abandon <original-revision-id>
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