Splitting a jj Changeset

Split the changeset

$ARGUMENTS

If

$ARGUMENTS

Table of Contents

1. Core Safety Principle: Duplicate First
2. Workflow Overview
3. Inspect the Changeset
4. Plan with the User
   • 4.1 How to group the changes
   • 4.2 What description each changeset should get
   • 4.3 How to validate each changeset
5. Duplicate the Changeset
6. Split the Changeset
   • 6.1 File-Path Split
   • 6.2 Hunk-Level Split
   • 6.3 Ordering matters
7. Set Descriptions
8. Verify the Split
   • 8.1 Verify completeness
   • 8.2 Verify individual changesets
   • 8.3 Run user-defined validation
9. Rebase Dependents
10. Clean Up
11. Key Commands Reference
12. When to Prompt the User
13. Limitations

1. Core Safety Principle: Duplicate First

Never edit the original changeset directly. Always duplicate it first, then work on the duplicate. This gives you a free undo — the original remains untouched until you're confident the split is correct.

# ALWAYS start here
jj duplicate <revset>       # Creates an identical copy; prints the new change ID

Only after the split is complete and verified should the original be abandoned:

jj abandon <original-revset>

This principle applies to every step below.

2. Workflow Overview

1. Inspect — understand what's in the changeset
2. Plan with the user — agree on groupings, descriptions, and validation criteria
3. Duplicate — create a safe working copy
4. Split — file-path-based or hunk-level
5. Describe — set meaningful descriptions on each resulting changeset
6. Verify — confirm no changes were lost, then run user-defined validation
7. Rebase dependents — ask the user if anything needs rebasing
8. Clean up — abandon the original

3. Inspect the Changeset

Before doing anything, understand what you're working with.

# Show the full diff with file names and stats
jj diff -r <revset> --stat
jj diff -r <revset>

# Show the changeset description and parents
jj log -r <revset>

Summarize for the user:

• How many files are changed
• Which files are logically related
• Whether there are clear groupings (e.g., "refactor" vs "feature" vs "tests")

4. Plan with the User

Always ask the user three things before proceeding.

4.1. How to group the changes

Present the file list and your suggested groupings, but let the user decide.

Example prompt:

This changeset touches 8 files. I see what looks like three logical groups:

1. Refactor:

   src/foo.rs

   ,

   src/bar.rs

   (signature changes)
2. Feature:

   src/new_thing.rs

   ,

   src/lib.rs

   (new functionality)
3. Tests:

   tests/test_new_thing.rs

   ,

   tests/test_foo.rs

Does this grouping look right? Would you like to split differently?

Mixed hunks within a single file: If a file has changes belonging to different logical groups, flag this to the user. The agent can handle hunk-level splits without interactivity — see 6.2 Hunk-Level Split. Present the hunks from the file and ask the user which hunks belong to which group.

4.2. What description each changeset should get

Ask for commit messages. Suggest defaults based on the groupings, but let the user confirm or override.

4.3. How to validate each changeset

Ask the user how to verify that each split changeset is correct beyond diffstat review. Examples:

How should I validate each split changeset? Some options:

• Build check:

  cargo build

  /

  cargo check

  after each split
• Test suite:

  cargo test

  (all tests, or a specific subset?)
• Lint/format:

  cargo clippy

  ,

  cargo fmt --check

• Diff review only: just show me the diffs and I'll eyeball them

You can specify different validation per group (e.g., "run tests for the feature changeset, diff review only for the refactor").

Store the validation plan — you'll execute it in Step 8.3.

5. Duplicate the Changeset

jj duplicate <revset>
# Note the new change ID from the output — this is your working copy

All subsequent operations target the duplicate, not the original.

6. Split the Changeset

Do not use

jj split -i

6.1. File-Path Split (When Each File Belongs to One Group)

jj split -r <rev> <paths...>

• First changeset: contains only the changes to the specified paths
• Second changeset: contains everything else

To split into more than two groups, run

jj split

jj duplicate <original>
# Say this produces change ID: abc

# First split: extract the refactor files
jj split -r abc src/foo.rs src/bar.rs
# Output tells you the two new change IDs.
# The "remainder" changeset (everything except foo+bar) — say it's def.

# Second split: extract the feature files from the remainder
jj split -r def src/new_thing.rs src/lib.rs
# Now you have three changesets: refactor, feature, tests

6.2. Hunk-Level Split (When a File Has Mixed Changes)

When a single file contains hunks belonging to different logical groups, you cannot use

jj split -r <rev> <path>

Strategy: For each group, create a new empty changeset off the parent, then populate it — using

jj restore --from <duplicate>

jj duplicate <original>
# Say this produces change ID: dup

# Identify the parent of the duplicate
jj log -r 'dup-' --no-graph -T 'change_id'
# Say the parent is: parent

# --- Group 1: refactor (whole file src/bar.rs + some hunks from src/foo.rs) ---

# Create an empty changeset on the parent
jj new <parent>
# Now the working copy is a new empty changeset — say it's g1

# Restore whole files that belong entirely to this group
jj restore --from <dup> src/bar.rs

# For src/foo.rs, only some hunks belong here.
# 1. Read the file at the parent state (the "before")
# 2. Read the full diff from the duplicate to understand all hunks
# 3. Apply only the desired hunks to produce the correct file content
# 4. Write the result directly
jj diff -r <dup> src/foo.rs   # Examine hunks, decide which belong to group 1
# Write the file with only the group-1 changes applied:
cat > src/foo.rs << 'EOF'
... file contents with only the refactor hunks applied ...
EOF

# --- Group 2: feature (rest of src/foo.rs + src/new_thing.rs + src/lib.rs) ---

jj new <g1>
# New empty changeset — say it's g2

# Restore whole files
jj restore --from <dup> src/new_thing.rs src/lib.rs

# For src/foo.rs, apply the remaining hunks (the ones NOT in group 1).
# The starting state is g1's version of foo.rs (which already has the refactor hunks).
# Write the final version that includes both refactor + feature hunks:
cat > src/foo.rs << 'EOF'
... file contents with the feature hunks applied on top of g1 ...
EOF

# --- Group 3: tests (remaining whole files) ---

jj new <g2>
jj restore --from <dup> tests/test_new_thing.rs tests/test_foo.rs

How to produce the partial file contents:

1. Run

   jj diff -r <dup> <path>

   to see all hunks for the file.
2. Read the file at the parent state:

   jj cat -r <parent> <path>

   .
3. Determine which hunks belong to the current group (from the plan agreed with the user in Step 4.1).
4. Apply only those hunks to the parent-state content to produce the desired file.
5. Write the result to the working copy.

This is more work than file-path splitting, but it gives full hunk-level control without any interactive commands.

6.3. Ordering Matters

Think about the dependency order of the groups. If the feature changes depend on the refactor, extract the refactor first so it becomes the parent of the feature changeset. Both

jj split

7. Set Descriptions

Apply the descriptions agreed in Step 4.2:

jj describe -r <revset1> -m "refactor: update foo and bar signatures"
jj describe -r <revset2> -m "feat: add new_thing implementation"
jj describe -r <revset3> -m "test: add tests for new_thing and updated foo"

8. Verify the Split

Verification has two parts: completeness (no changes lost) and correctness (each changeset is valid on its own).

8.1. Verify Completeness — No Changes Lost

Use

jj interdiff

jj interdiff --from <original-revset> --to <last-split-revset>

If the split is correct, this produces no output (empty diff). Any output means changes were lost or duplicated.

If

jj interdiff

diff <(jj diff -r <original-revset>) <(jj diff -r <first-split> && jj diff -r <second-split> && jj diff -r <third-split>)

8.2. Verify Individual Changesets — Stat Review

Show the user the stat summary of each changeset:

jj diff -r <revset1> --stat
jj diff -r <revset2> --stat
jj diff -r <revset3> --stat

8.3. Run User-Defined Validation

Execute the validation plan from Step 4.3. For each changeset, check out the state at that revision and run the agreed checks:

# Example: validate that the refactor changeset builds
jj new <revset1>
cargo check
# ... then validate the next changeset, etc.

If any validation fails, report the failure to the user and ask how to proceed — do not abandon the original or continue automatically.

Present a summary of all verification results and ask the user to confirm before proceeding.

9. Rebase Dependents (If Needed)

Only after all verification passes and the user has confirmed, check whether other changesets depend on the original:

jj log -r '<original-revset>+'

If there are dependents, ask the user which split changeset they should be rebased onto:

The following changesets are children of the original:

• xyz

  ("add benchmarks")

Which split changeset should they be rebased onto?

1. <revset1>

   — "refactor: update foo and bar signatures"

2. <revset2>

   — "feat: add new_thing implementation"

3. <revset3>

   — "test: add tests for new_thing and updated foo"

Then rebase as directed:

jj rebase -s <dependent> -o <new-parent>

10. Clean Up

Once everything is verified and dependents are handled:

jj abandon <original-revset>

11. Key Commands Reference

jj duplicate <revset>

jj split -r <revset> <paths...>

jj restore --from <src> [paths...]

jj interdiff --from <a> --to <b>

jj cat -r <revset> <path>

jj describe -r <revset> -m "..."

jj abandon <revset>

jj rebase -s <src> -o <dest>

jj diff -r <revset> --stat

jj diff -r <revset>

jj log -r <revset>

jj new <revset>

12. When to Prompt the User

Always ask before:

• Deciding how to group changes (4.1)
• Setting commit descriptions (4.2)
• Defining validation criteria for each changeset (4.3)
• Proceeding after any validation failure (8.3)
• Rebasing dependent changesets (9)
• Abandoning the original changeset (10)

Don't ask, just do:

• jj duplicate

  — always safe

• jj diff --stat

  /

  jj diff

  — read-only inspection

• jj log

  — read-only inspection

• jj interdiff

  — read-only verification
• Running the agreed validation commands (8.3)

13. Limitations

• No interactive commands. Never use

  jj split -i

  or any command that opens an editor. Use file-path-based

  jj split

  for whole-file splits and the manual

  jj new

  +

  jj restore

  + file-write approach for hunk-level splits.
• Hunk-level splits require care. When manually applying hunks, verify the resulting file contents are correct. A mistake here is harder to spot than a wrong file-level grouping. The completeness check in 8.1 will catch lost or duplicated changes.