The jj Field Guide

Jujutsu (jj) version control, finally explained in plain language. Verified on jj 0.44.0. The full illustrated guide is embedded above (and downloadable) — this page is the fast reference; the PDF is the long-form walkthrough with real command output.

One way to do each thing — the way that works every time. No aliases, no shortcuts, no “you could also…”.

The ritual — how a note gets to GitHub

The whole game is four moves, in order:

jj st                          # 1. look: what did I change?
jj commit -m "update: ..."     # 2. seal it with a message
jj bookmark set main -r @-      # 3. move the sticky note onto the sealed work
jj git push                     # 4. send it to GitHub

And once per computer, ever — not before every push:

jj bookmark track main@origin   # link your main to GitHub's main. ONCE.

You can drop a step: moving a bookmark just repoints a label — it creates nothing to commit. Commit once, move the note, push. Three moves, not five — a second jj commit only seals an empty change.

The three ideas that replace everything git taught you

1. Your folder is already a commit, called @. There is no staging area and no jj add. Any jj command snapshots every edited file into @ first — edit a note, run jj st, and your edits are already inside @.
2. @- is the commit right below you. History is a stack: @ on top, its parent @-, then @--. jj commit seals your work and opens a fresh empty @ on top — so the work you just finished now lives at @-. That is why the bookmark step says -r @-, not -r @.
3. Bookmarks never move by themselves. A bookmark is jj’s word for a git branch — just a named sticky note stuck to one commit. Git secretly drags the branch pointer forward when you commit; jj does not. Nothing moves a bookmark except you (jj bookmark set main -r @-). GitHub reads main’s sticky note, so until you move it, GitHub sees nothing new.

In the full guide (PDF)