dojos · docs/the-dojos-book.md
Rendered<br>Source<br>Raw
☯ The Dojos Book<br>*A friendly tour of `dj`, for developers who already know Git*
Welcome<br>**Why `dj`? `jj` goodness without the pain: same Git words, fewer Git gotchas.**
You know Git. You've typed `git add -p` more times than you'd like to admit,<br>you've lost work to a bad `checkout`, and you've heard that this "jj" thing is<br>supposed to be better — but every time you looked into it, it came with a<br>vocabulary lesson attached: revsets, bookmarks, `@`.
`dj` is a small command-line tool that wraps [Jujutsu](https://jj-vcs.dev)<br>(`jj`) in Git's own words. You keep typing `commit`, `push`, `pull`, `tag` —<br>the verbs don't change — but underneath, a few of Git's worst habits quietly<br>stop happening. No staging. No lost work. No more "fatal: your local changes<br>would be overwritten." And when something *does* go sideways, one command —<br>`dj undo` — takes it back, no matter what it was.
The book has two parts:
- **Section 1** meets you where you are: an existing project, probably on<br>GitHub. You install `dj`, point it at a repo you already have, and spend a<br>day learning what gets easier — without touching anyone's servers.<br>- **Section 2** is for when you want more: hosting your own projects on<br>**dojos.dev**, with code reviews (we call them **Reviews**), issues, and an<br>AI agent that already knows how to drive your version control for you.
You can stop after Section 1 forever, if all you want is a calmer Git. Or you<br>can keep going. Either is a complete way to use `dj`.
Throughout, we'll work on a little project called **biscuit** — a toy to-do<br>list app, just complex enough to need real version control and just small<br>enough that nothing here distracts you from the tool. Swap it for your own<br>repo any time; nothing below is biscuit-specific.
Let's begin.
Table of Contents<br>- **[Cheat Sheet](#cheat-sheet)**<br>- **[Section 1 — Bring `dj` home](#section-1-bring-dj-home)**<br>1. [Say hello](#1-say-hello)<br>2. [First contact](#2-first-contact)<br>3. [No more staging](#3-no-more-staging)<br>4. [The work is always already saved](#4-the-work-is-always-already-saved)<br>5. [Building a little stack](#5-building-a-little-stack)<br>6. [Push, same as ever](#6-push-same-as-ever)<br>7. [The undo superpower](#7-the-undo-superpower)<br>8. [Pulling without the wall](#8-pulling-without-the-wall)<br>9. [Branching, lightly](#9-branching-lightly)<br>10. [Looking around](#10-looking-around)<br>11. [Fixing a typo](#11-fixing-a-typo)<br>12. [Tidying up](#12-tidying-up)<br>13. [Wrapping up Section 1](#13-wrapping-up-section-1)<br>- **[Section 2 — Moving in: dojos.dev and dojos.name](#section-2-moving-in-dojosdev-and-dojosname)**<br>1. [Why bother moving in](#1-why-bother-moving-in)<br>2. [Logging in](#2-logging-in)<br>3. [Creating (or linking) a Dojo](#3-creating-or-linking-a-dojo)<br>4. [The `.dojo` file](#4-the-dojo-file)<br>5. [Two ways to land work](#5-two-ways-to-land-work)<br>6. [Reviews — open, push, merge](#6-reviews-open-push-merge)<br>7. [Issues](#7-issues)<br>8. [Tags and releases](#8-tags-and-releases)<br>9. [Keys, for teams and robots](#9-keys-for-teams-and-robots)<br>10. [The AI angle](#10-the-ai-angle)<br>11. [Browsing it all](#11-browsing-it-all)<br>12. [Wrapping up Section 2](#12-wrapping-up-section-2)<br>- **[Glossary](#glossary)**<br>- **[Index](#index)**
Cheat Sheet<br>Keep this page open. Everything on it is explained properly later — this is<br>just so you don't have to go hunting.
### Your everyday loop
```<br>dj where am I? (status of @, remote, Dojo)<br>dj commit -m "message" label this change, start a fresh one (no staging!)<br>dj push upload your work<br>dj pull fetch + rebase your work onto the new tip<br>dj undo reverse whatever you just did<br>```
### Looking around
```<br>dj log your line's history<br>dj diff what's changed right now<br>dj show one change, in full<br>dj grep PATTERN search tracked files<br>dj blame PATH who wrote each line, and in which change<br>```
### Branching (optional — most days you won't)
```<br>dj branch NAME name the current change<br>dj switch NAME move to a named line (never stashes, never blocks)<br>dj branch -d NAME delete a line, locally and on the remote<br>```
### Fixing mistakes
```<br>dj commit --amend -m "…" re-message the current change, in place<br>dj restore [PATHS] discard uncommitted edits (bare = discard everything)<br>dj undo reverse the last operation, whatever it was<br>```
### dojos.dev (once you've moved in — Section 2)
```<br>dj login enroll your SSH key (one-time, browser-approved)<br>dj init --create turn the current repo into a hosted Dojo<br>dj clone user/repo clone a Dojo by its handle<br>dj review open propose your current change as a Review<br>dj review push land more edits into an open Review + push it<br>dj review merge merge a Review<br>dj issue create -t "…" file an issue<br>dj issue fix mark an issue resolved<br>dj tag v1.2.3 tag a release<br>dj skill teach your AI assistant to use dj instead of git<br>```
### Old habit → new habit
| You used to type… | Now you type… | What's different...