commit 797fea7cfba99e03922177d13b186202ea676cfd
parent a67f344e8a7644d26b0329973d951700eab7b919
Author: $: DAΞMON <zer0sec.xp@icloud.com>
Date: Fri, 28 Aug 2026 21:16:51 +0100
sheets: add The jj Field Guide (git-workflow) with embedded PDF
New git-workflow sheet mirroring the vault's jj (Jujutsu) field guide, with
the PDF embedded + downloadable via the sheet `pdf:` frontmatter field.
PDF asset lives in public/pdfs/jj-field-guide.pdf.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01A9rEmaZyHxxnQa9wwDtDKF
Diffstat:
2 files changed, 57 insertions(+), 0 deletions(-)
diff --git a/public/pdfs/jj-field-guide.pdf b/public/pdfs/jj-field-guide.pdf
Binary files differ.
diff --git a/src/content/sheets/git-workflow/jj-field-guide.md b/src/content/sheets/git-workflow/jj-field-guide.md
@@ -0,0 +1,57 @@
+---
+title: "The jj Field Guide"
+description: "Jujutsu (jj) version control in plain language: the save → bookmark → push ritual, what @ and @- really mean, bookmarks, syncing with GitHub, and undoing anything."
+category: git-workflow
+tags: [git, jj, jujutsu, version-control, workflow]
+tools: [jj]
+difficulty: beginner
+updated: "2026-08-28"
+source: "vault:04Tools/jj-field-guide/jj-field-guide.pdf"
+pdf: jj-field-guide.pdf
+---
+
+# 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:
+
+```sh
+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:
+
+```sh
+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)
+
+| § | Topic |
+|---|---|
+| 01 | The big picture — the three ideas that replace git |
+| 02 | The words — `@`, `@-`, change, bookmark, `main@origin`, tracked |
+| 03 | A worked example — built from nothing, on real output |
+| 04 | Save your work — the everyday loop and commit messages |
+| 05 | Bookmarks, finally explained |
+| 06 | Push — what "track" actually means |
+| 07 | Fetch & sync — get what's on GitHub, safely |
+| 08 | Side branches — drafts that don't touch main |
+| 09 | When things go wrong — undo anything |
+| 10 | The reference card — every command, one place |