working-with-jj

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