| name | working-with-jj |
| description | 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. |
| version_target | 0.36.x |
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 undo goes further back, jj redo reverses)
- 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
.jj and .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]
jj log -r <revset> -G
jj show -r <rev>
jj evolog -r <rev> [-p]
jj new [-A] <base>
jj new --no-edit <base>
jj edit <rev>
jj desc -r <rev> -m "text"
jj metaedit -r <rev> -m "text"
jj diff
jj diff -r <revset>
jj diff -f <rev1> -t <rev2>
jj file show -r <rev> <fileset>
jj file show -r <rev> **/*.md -T '"=== " ++ path ++ " ===\n"'
jj restore <fileset>
jj restore --from <commit-id> <fileset>
jj split -r <rev> <paths> -m "text"
jj absorb
jj rebase -s <src> -o <dest>
jj rebase -r <rev> -o <dest>
jj file annotate <path>
jj bisect run -- <cmd>
Additional Commands
jj undo
jj redo
jj sign -r <rev>
jj unsign -r <rev>
jj revert -r <rev>
jj tag set <name> -r <rev>
jj tag delete <name>
jj git colocation enable
jj git colocation disable
Quick Revset Reference
@, @-, @--
::@
@::
mine()
conflicted()
visible()
hidden()
description(substring-i:"text")
subject(substring:"text")
signed()
A | B, A & B, A ~ B
change_id(prefix)
parents(x, 2)
exactly(x, 3)
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"
jj new --no-edit parent -m "A"; jj new --no-edit parent -m "B"
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
jj rebase -s xyz -d main
5. Symbol expressions are stricter (v0.32+)
Revset symbols no longer resolve to multiple revisions:
jj log -r abc
jj log -r 'change_id(abc)'
jj log -r 'bookmarks(abc)'
6. Glob patterns are default in filesets (v0.36+)
jj diff 'src/*.rs'
jj diff 'cwd:"src/*.rs"'
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
jj op restore <op-id>
References
- The
jj exe 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
--help page
references/command-syntax.md - Command flag details
references/batch-operations.md - Complex batch transformations on revision descriptions