gh-ypares-agent-skills-ypares-agent-skills/skills/working-with-jj/SKILL.md

name, description

name	description
working-with-jj	Expert guidance for using JJ (Jujutsu) version control system. Use when working with JJ, whatever the subject. Operations, revsets, templates, TODO commit workflows, debugging change evolution, etc. Covers JJ commands, template system, evolog, operations log, and specific JJ workflows.

JJ (Jujutsu) Version Control Helper

Core Principles

• Change IDs (immutable) vs Commit IDs (content-based hashes that change on edit)
• Operations log - every operation can be undone with jj op restore
• No staging area - working copy auto-snapshots
• Conflicts don't block - resolve later
• Commits are lightweight - edit freely

Essential Commands

jj log -r <revset>                    # View history
jj evolog -r <rev> --git              # Change evolution (with diffs)
jj new <base>                         # Create revision and edit it
jj new --no-edit <base>               # Create without switching (for TODOs)
jj edit <rev>                         # Switch to editing revision
jj desc -r <rev> -m "text"            # Set description

jj diff                               # Changes in @
jj diff -r <rev>                      # Changes in revision
jj restore <path>                     # Discard changes to file
jj restore --from <rev> <path>        # Restore from another revision

jj split -r <rev>                     # Split into multiple commits
jj squash                             # Squash @ into parent
jj squash --into <dest>               # Squash @ into specific revision
jj absorb                             # Auto-squash into right ancestors

jj rebase -s <src> -d <dest>          # Rebase with descendants
jj rebase -r <rev> -d <dest>          # Rebase single revision only

Quick Revset Reference

@, @-, @--                            # Working copy, parent, grandparent
::@                                   # Ancestors
mine()                                # Your changes
conflict()                            # Has conflicts
description(substring:"text")         # Match description
A | B, A & B, A ~ B                   # Union, intersection, difference

See references/revsets.md for comprehensive revset patterns.

Common Pitfalls

1. Use -r not --revisions

jj log -r xyz          # ✅
jj log --revisions xyz # ❌

2. Use --no-edit for parallel branches

jj new parent -m "A"; jj new parent -m "B"           # ❌ B is child of A!
jj new --no-edit parent -m "A"; jj new --no-edit parent -m "B"  # ✅ Both children of parent

3. Quote revsets in shell

jj log -r 'description(substring:"[todo]")'    # ✅

Scripts

Helper scripts in scripts/. Add to PATH or invoke directly.

Script	Purpose
jj-show-desc [REV]	Get description only
jj-show-detailed [REV]	Detailed info with git diff
jj-todo-create <PARENT> <TITLE> [DESC]	Create TODO (stays on @)
jj-todo-done [NEXT_REV]	Complete current TODO, start next
jj-flag-update <REV> <TO_FLAG>	Update status flag (auto-detects current)
jj-find-flagged [FLAG]	Find flagged revisions
jj-parallel-todos <PARENT> <T1> <T2>...	Create parallel TODOs
jj-desc-transform <REV> <CMD...>	Pipe description through command
jj-batch-desc <SED_FILE> <REV...>	Batch transform descriptions
jj-checkpoint [NAME]	Record op ID before risky operations

These scripts are notably useful if you are working using a "TODO Commit Workflow": see references/todo-workflow.md for structured TODO planning, parallel task DAGs, and AI-assisted workflows.

Recovery

jj op log              # Find operation before problem
jj op restore <op-id>  # Restore to that state

References

• references/todo-workflow.md - Structured TODO planning, parallel DAGs, AI workflows
• references/revsets.md - Full revset syntax and patterns
• references/templates.md - Template language and custom output
• references/git-remotes.md - Bookmarks, push/fetch, remote workflows
• references/command-syntax.md - Command flag details
• references/batch-operations.md - Complex batch transformations