jj-workflow

jj-workflow — Natural Language to jj Operations

Translate natural language VCS requests into correct jj commands when working in a Jujutsu repository.

When to Use

Use when ALL of these conditions are met:

1. A .jj directory exists in the project root (verify with ls -d .jj 2>/dev/null)
2. The user describes a version control operation in natural language
3. The operation maps to one or more jj commands

Do NOT use when:

• There is no .jj directory (this is not a jj repo)
• The user is explicitly asking for git commands in a non-jj context
• The user already typed the exact jj command they want to run

Operation Reference

Creating and Navigating Changes

User Intent	jj Command	Notes
Start new work / new change	jj new	Creates empty change on top of current
New change from specific parent	jj new <rev>	Branch from a specific revision
New change with multiple parents	jj new <rev1> <rev2>	Creates a merge change
Go back and edit a past change	jj edit <rev>	Moves working copy to that change
See what I'm working on	jj status	Shows working copy status

Describing and Modifying Changes

User Intent	jj Command	Notes
Add/update commit message	jj describe -m "message"	Describes current working copy
Describe a different change	jj describe <rev> -m "msg"	Describe any change
Combine with parent	jj squash	Squash current into parent
Squash specific change into another	jj squash --from <src> --into <dst>	Flexible squash
Split change into two	jj split	Interactive split
Split specific files out	jj split <paths>	Split by file
Discard / throw away a change	jj abandon <rev>	Remove change from history

Rebasing and Reorganizing

User Intent	jj Command	Notes
Move change to different parent	jj rebase -r <rev> -d <dest>	Rebase single change
Move change and its descendants	jj rebase -s <rev> -d <dest>	Rebase subtree
Move change and reparent children	jj rebase -b <rev> -d <dest>	Rebase branch
Put change on top of trunk/main	jj rebase -r <rev> -d 'trunk()'	Common rebase target

Bookmarks (Branches)

User Intent	jj Command	Notes
Create / move a bookmark	jj bookmark set <name> -r <rev>	Set bookmark at revision
List bookmarks	jj bookmark list	Show all bookmarks
Delete a bookmark	jj bookmark delete <name>	Remove bookmark
Track remote bookmark	jj bookmark track <name>@<remote>	Start tracking

Collaboration (Colocated)

User Intent	jj Command	Notes
Push changes	jj git push	Push bookmarked changes
Fetch latest	jj git fetch --all-remotes	Fetch from all remotes
Import git refs	jj git import	Sync git state into jj
Export jj to git	jj git export	Sync jj state to git

Other Operations

User Intent	jj Command	Notes
Copy a change	jj duplicate <rev>	Duplicate without moving
Reverse a change	jj backout -r <rev>	Create inverse change
Resolve conflicts	jj resolve	Launch merge tool
Show diff	jj diff	Current change diff
Show diff of specific change	jj diff -r <rev>	Diff for any change
Restore file from another change	jj restore --from <rev> <path>	Restore specific file
Create workspace	jj workspace add <path>	Multiple working copies
Undo last operation	jj op undo	Undo last jj operation

Execution Pattern

When handling a natural language VCS request:

1. Detect context: Verify .jj exists. Check if colocated (.git also exists).
2. Show current state: Run jj log --limit 5 to understand the current change graph.
3. Analyze intent: Map the user's natural language to the appropriate jj command(s).
4. Explain before executing: Tell the user what command(s) will run and why.
5. Execute: Run the command(s).
6. Show result: Display the updated state with jj log --limit 5 or jj status.

Multi-Step Operations

Some requests require multiple commands. Common patterns:

"Move this change before that one":

1. jj rebase -r <this> -d <that-parent>
2. jj rebase -r <that> -d <this>

"Start a new feature from main":

1. jj new 'trunk()'
2. jj bookmark set feature-name

"Clean up and submit":

1. jj squash (combine with parent if needed)
2. jj describe -m "message"
3. jj bookmark set <name> -r @
4. jj git push (if colocated)

Revision Syntax Quick Reference

Help users with jj's revision syntax when needed:

• @ — current working copy
• @- — parent of working copy
• trunk() — main/master bookmark
• mine() — changes authored by current user
• empty() — changes with no diff
• conflict() — changes with conflicts
• <rev>- — parent of revision
• <rev>+ — children of revision
• <rev1>::<rev2> — range between revisions