jj-field-guide.md (3080B)
1 --- 2 title: "The jj Field Guide" 3 description: "Jujutsu (jj) version control in plain language: the save → bookmark → push ritual, what @ and @- really mean, bookmarks, syncing with GitHub, and undoing anything." 4 category: git-workflow 5 tags: [git, jj, jujutsu, version-control, workflow] 6 tools: [jj] 7 difficulty: beginner 8 updated: "2026-08-28" 9 source: "vault:04Tools/jj-field-guide/jj-field-guide.pdf" 10 pdf: jj-field-guide.pdf 11 --- 12 13 # The jj Field Guide 14 15 **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. 16 17 > **One way to do each thing** — the way that works every time. No aliases, no shortcuts, no "you could also…". 18 19 ## The ritual — how a note gets to GitHub 20 21 The whole game is four moves, in order: 22 23 ```sh 24 jj st # 1. look: what did I change? 25 jj commit -m "update: ..." # 2. seal it with a message 26 jj bookmark set main -r @- # 3. move the sticky note onto the sealed work 27 jj git push # 4. send it to GitHub 28 ``` 29 30 And **once per computer, ever** — not before every push: 31 32 ```sh 33 jj bookmark track main@origin # link your main to GitHub's main. ONCE. 34 ``` 35 36 > **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. 37 38 ## The three ideas that replace everything git taught you 39 40 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 `@`. 41 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 @`. 42 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. 43 44 ## In the full guide (PDF) 45 46 | § | Topic | 47 |---|---| 48 | 01 | The big picture — the three ideas that replace git | 49 | 02 | The words — `@`, `@-`, change, bookmark, `main@origin`, tracked | 50 | 03 | A worked example — built from nothing, on real output | 51 | 04 | Save your work — the everyday loop and commit messages | 52 | 05 | Bookmarks, finally explained | 53 | 06 | Push — what "track" actually means | 54 | 07 | Fetch & sync — get what's on GitHub, safely | 55 | 08 | Side branches — drafts that don't touch main | 56 | 09 | When things go wrong — undo anything | 57 | 10 | The reference card — every command, one place |