working-with-jj

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.

| 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 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