gh-towry-dots-conf-claude-local-marketplace/skills/git-jj/references/jj_workflows.md

Jujutsu (jj) Workflows Guide

Version: jj 0.9+

Core Concepts

Key differences from Git:

• Auto-snapshotting: Most commands automatically commit working-copy changes
• No staging area: All tracked files are automatically included
• @ symbol: Always represents current working-copy commit
• Immutable history: Operations create new commits; old commits remain accessible

Quick Reference

Status & Inspection

jj status                          # Snapshot and show status
jj diff --git                      # Working copy changes
jj diff --git -r <rev>             # Changes in specific revision
jj log -n 10                       # History (graph by default)
jj show <rev>                      # Commit details

Creating & Modifying Commits

jj describe -m "message"           # Update current commit description
jj describe -r <rev> -m "msg"      # Update specific revision
jj commit -m "message"             # Create new commit, move @ forward
jj new -m "message"                # Create empty checkpoint commit
jj squash                          # Fold @ into parent (amend-like)
jj squash -f <src> -t <dest>       # Move changes between commits
jj abandon <rev>                   # Remove commit from history
jj duplicate <rev>                 # Cherry-pick equivalent
jj rebase -r <rev> -d <dest>       # Rebase revision
jj edit <rev>                      # Edit specific revision directly

File Operations

jj restore <file>                  # Restore from parent
jj restore --from <rev> <file>     # Restore from specific revision
jj file track <path>               # Start tracking
jj file untrack <path>             # Stop tracking

Bookmarks (Branches)

jj bookmark list                   # List all
jj bookmark create <name>          # Create at @
jj bookmark set <name> -r <rev>    # Point to revision
jj bookmark delete <name>          # Delete
jj bookmark track <name>@<remote>  # Set up tracking

Remotes

jj git fetch                       # Fetch all
jj git fetch --remote <name>       # Fetch specific
jj git push -b <bookmark>          # Push bookmark
jj git push --all                  # Push all bookmarks

Workspaces

jj workspace add <path>            # Create (like git worktree)
jj workspace list                  # List all
jj workspace forget <name>         # Remove

WIP Commit Pattern

# Start work
jj describe -m "WIP: feature"

# Continue working (auto-snapshots on jj commands)

# Finalize (if @ is the WIP commit)
jj commit -m "feat: completed"
# use describe with `-r` if wip commits is in parents.

# Or squash into parent
jj squash

Before committing, check state:

jj --no-pager status
jj --no-pager log -r '@-'          # Check parent

Conflict Resolution

JJ allows committing conflicts and resolving them later.

Recommended: Resolve in New Commit

jj new <conflicted-commit>         # Create child
# ... edit files to resolve ...
jj diff                            # Review resolutions
jj squash                          # Merge back into parent

Alternative: Direct Edit

jj edit <conflicted-commit>
# ... resolve conflicts ...
jj describe -m "resolved conflicts"

External Tool

jj resolve                         # Opens merge tool (2-sided conflicts only)

Git Command Mappings

Git	jj
git status	jj status
git diff	jj diff --git
git add .	(automatic)
git commit -m	jj commit -m
git commit --amend	jj squash or jj describe
git log	jj log
git branch	jj bookmark list
git checkout <branch>	jj edit <bookmark>
git merge <branch>	jj new <rev1> <rev2>
git rebase	jj rebase -r <rev> -d <dest>
git cherry-pick	jj duplicate <rev>
git stash	jj new (checkpoint)
git worktree add	jj workspace add

Revision Syntax

• @ - Working copy
• @- - Parent of working copy
• <bookmark> - Bookmark target
• <rev>:: - Ancestors
• ::<rev> - Descendants
• <rev1>..<rev2> - Range
• trunk() - Main branch
• file('<path>') - Revisions modifying file

Fileset Language

Patterns

Pattern	Description
"path"	CWD-relative prefix (recursive)
file:"path"	Exact file match
glob:"*.rs"	CWD-relative glob
root:"path"	Workspace-relative prefix
root-glob:"**/*.rs"	Workspace-relative glob

Operators

Op	Meaning	Example
~x	NOT	~Cargo.lock
x & y	AND	src & glob:"*.rs"
x ~ y	MINUS	src ~ glob:"*test*"
x | y	OR	src | tests

Examples

jj diff '~Cargo.lock'                        # Exclude file
jj diff 'glob:"**/*.md"'                     # Only markdown
jj log -r 'trunk()..@ & file("src/core")'    # Commits touching path
jj diff --git -f "trunk()" -t "@"            # Diff vs trunk

Important Notes

1. Always use -m flag in non-interactive contexts (scripts, LLM agents)
2. Check status before critical ops: jj --no-pager status
3. Conflicts are first-class: Can be committed, shared, resolved incrementally
4. Operations are recoverable: jj op log shows history