
working-with-jj
Expert guidance for using JJ (Jujutsu) version control system. Use when working with JJ, whatever the subject. Operations, revsets, templates, debugging change evolution, etc. Covers JJ commands, template system, evolog, operations log, and interoperability with git remotes.
- Installs
- 68
- Last 24h
- —
- Trending rank
- —
- Security
- Not audited
Install
Works with every agent the skills CLI supports.
npx skills add https://github.com/ypares/agent-skills --skill working-with-jj- 01
Install
Run the command in your project. The CLI asks which agents to install for.
- 02
Describe the task
Ask your agent for something this skill covers. It loads working-with-jj automatically when relevant.
- 03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.
SKILL.md
The instructions your agent reads when the skill is triggered.
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 (progressive: multiple
jj undogoes further back,jj redoreverses) - No staging area - working copy auto-snapshots
- Conflicts don't block - resolve later
- Commits are lightweight - edit freely
- Colocated by default - Git repos have both
.jjand.git(since v0.34) - Three DSLs:
- revsets: select across revisions - a revision (change) ID is a trivial but fully valid singleton revset
- filesets: select across files in the repository - a regular filepath is a trivial but fully valid singleton fileset
- templates: select which info to log and how to show it
- Many jj commands expect expressions using either of these DSLs, to select what to show/operate on
Essential Commands
jj log -r <revset> [-p] # View history (--patch/-p: include diffs, --count: just count)
jj log -r <revset> -G # -G is short for --no-graph
jj show -r <rev> # Show revision details (description + diff)
jj evolog -r <rev> [-p] # View a revision's evolution
jj new [-A] <base> # Create revision and edit it (-A: insert between <base> and its children rather than just on top of base)
jj new --no-edit <base> # Create without switching
jj edit <rev> # Switch to editing revision
jj desc -r <rev> -m "text" # Set description
jj metaedit -r <rev> -m "text" # Modify metadata (author, timestamps, description)
jj diff # Changes in @
jj diff -r <revset> # Changes in revset (need to be contiguous)
jj diff -f <rev1> -t <rev2> # Differences between two states
jj file show -r <rev> <fileset> # Show file contents at revision (without switching)
jj file show -r <rev> **/*.md -T '"=== " ++ path ++ " ===\n"' # Multiple files with path headers
jj restore <fileset> # Discard changes to files
jj restore --from <commit-id> <fileset> # Restore from another revision/commit
jj split -r <rev> <paths> -m "text" # Split into two revisions
jj absorb # Auto-squash changes into ancestor commits
jj rebase -s <src> -o <dest> # Rebase with descendants onto <dest>
jj rebase -r <rev> -o <dest> # Rebase single revision onto <dest>
# NOTE: -d/--destination is deprecated, use -o/--onto instead
jj file annotate <path> # Blame: who changed each line
jj bisect run -- <cmd> # Binary search for bug-introducing commit
Additional Commands
jj undo # Undo last operation (progressive - repeat to go further back)
jj redo # Redo undone operation
jj sign -r <rev> # Cryptographically sign commit
jj unsign -r <rev> # Remove signature
jj revert -r <rev> # Create commit that reverts changes (replaces old jj backout)
jj tag set <name> -r <rev> # Create/update local tag
jj tag delete <name> # Delete local tag
jj git colocation enable # Convert to colocated repo
jj git colocation disable # Convert to non-colocated
Quick Revset Reference
@, @-, @-- # Working copy, parent(s), grandparent(s)
::@ # Ancestors
@:: # Descendants
mine() # Your changes
conflicted() # Has conflicts (renamed from conflict() in v0.33)
visible() # Visible revisions (built-in alias)
hidden() # Hidden revisions (built-in alias)
description(substring-i:"text") # Match description (partial, case-insensitive)
subject(substring:"text") # Match first line only
signed() # Cryptographically signed commits
A | B, A & B, A ~ B # Union, intersection, difference
change_id(prefix) # Explicit change ID prefix lookup
parents(x, 2) # Parents with depth
exactly(x, 3) # Assert exactly N revisions
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 -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]")' # ✅
4. Use -o/--onto instead of -d/--destination (v0.36+)
jj rebase -s xyz -o main # ✅ New syntax
jj rebase -s xyz -d main # ⚠️ Deprecated (still works but warns)
5. Symbol expressions are stricter (v0.32+)
Revset symbols no longer resolve to multiple revisions:
jj log -r abc # ❌ Error if 'abc' matches multiple change IDs
jj log -r 'change_id(abc)' # ✅ Explicitly query by prefix
jj log -r 'bookmarks(abc)' # ✅ For bookmark name patterns
6. Glob patterns are default in filesets (v0.36+)
jj diff 'src/*.rs' # Matches glob pattern by default
jj diff 'cwd:"src/*.rs"' # Use cwd: prefix for literal path with special chars
Scripts
Helper scripts in scripts/. Add to PATH or invoke directly.
| Script | Purpose |
|---|---|
jj-show-desc [REV] | Print full description only |
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 |
Recovery
jj op log # Find operation before problem
jj op restore <op-id> # Restore the WHOLE repository (history included) to that state
References
- The
jjexe is self-documenting:- Run
jj help -k bookmarks- JJ bookmarks, how they relate to Git branches and how to push/fetch them from Git remotes - Run
jj help -k revsets- Revset DSL syntax and patterns - Run
jj help -k filesets- Filepath selection DSL, ie. how to tell jj commands to operate only on specific files - Run
jj help -k templates- Template language and custom output - All jj subcommands have a pretty detailed
--helppage
- Run
references/command-syntax.md- Command flag detailsreferences/batch-operations.md- Complex batch transformations on revision descriptions
FAQ
What does the working-with-jj skill do?
Expert guidance for using JJ (Jujutsu) version control system. Use when working with JJ, whatever the subject. Operations, revsets, templates, debugging change evolution, etc. Covers JJ commands, template system, evolog, operations log, and interoperability with git remotes.
How do I install working-with-jj?
Run npx skills add https://github.com/ypares/agent-skills --skill working-with-jj in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/working-with-jj/ (personal) or .claude/skills/working-with-jj/ (project).
Which AI agents can use working-with-jj?
Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.
Is working-with-jj safe to install?
No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.
Who maintains working-with-jj?
It is published by ypares in ypares/agent-skills. It has 68 recorded installs.
More from ypares/agent-skills
searxng-search
ypares/agent-skills
Enhanced web and package repository search using local SearXNG instance
textual-builder
ypares/agent-skills
Build Text User Interface (TUI) applications using the Textual Python framework (v0.86.0+). Use when creating terminal-based applications, prototyping card games or interactive CLIs, or when the user mentions Textual, TUI, or terminal UI. Includes comprehensive reference documentation, card game starter template, and styling guides.
typst-writer
ypares/agent-skills
Write correct and idiomatic Typst code for document typesetting. Use when creating or editing Typst (.typ) files, working with Typst markup, or answering questions about Typst syntax and features. Focuses on avoiding common syntax confusion (arrays vs content blocks, proper function definitions, state management).
github-pr-workflow
ypares/agent-skills
Open the skill to read its SKILL.md instructions.
cursor-agent-supervisor
ypares/agent-skills
Offloading tasks with a well-defined scope to sub-agents, for instance to use a sub-agent to implement a set of specs. Use this skill whenever a task should not need a broad knowledge of the whole project
nushell-usage
ypares/agent-skills
Essential patterns, idioms, and gotchas for writing Nushell code. Use when writing Nushell scripts, functions, or working with Nushell's type system, pipelines, and data structures. Complements plugin development knowledge with practical usage patterns.
Popular code quality & workflow skills
grill-me
mattpocock/skills
A relentless interview to sharpen a plan or design.
improve-codebase-architecture
mattpocock/skills
Scan a codebase for deepening opportunities, present them as a visual HTML report, then grill through whichever one you pick.
handoff
mattpocock/skills
Compact the current conversation into a handoff document for another agent to pick up.
domain-modeling
mattpocock/skills
Build and sharpen a project's domain model. Use when discussing codebase terminology, writing or editing a GLOSSARY.md, or recording or editing an ADR.
codebase-design
mattpocock/skills
Shared vocabulary for designing deep modules. Use when the user wants to design or improve a module's interface, find deepening opportunities, decide where a seam goes, make code more testable or AI-navigable, or when another skill needs the deep-module vocabulary.
diagnosing-bugs
mattpocock/skills
Diagnosis loop for hard bugs and performance regressions. Use when the user says "diagnose"/"debug this", or reports something broken/throwing/failing/slow.