With JavaScript, this picture moves through the lesson below one step at a time. Orbs
are commits: amber with @ for the working copy, red with a cross for a
conflict. Diamonds are shared commits that jj will not rewrite. Dashed rings are older
versions, kept. The small cubes are the files a commit changes, and the pills are
bookmarks.
The working copy is a commit
1. A repository, standing up
Each shape is a commit, and newer work sits higher. The diamonds are commits already shared with others, which jj will not rewrite. The orb marked @ is your working copy. In jj the working copy is a real commit, not a staging area off to the side.
$jj log
@ mzxutzyn1e89af9e
│ (empty)(no description set)
◆ rovxnrwu00fb8673main
│ Start the timer app
◆ zzzzzzzz root() 00000000
2. Edit files. That is all
You change app.js and style.css. There is no add and no staging. The next jj command you run snapshots your files straight into @. The small blocks circling a commit are the file changes it holds.
$jj st
Working copy changes:
M app.js
M style.css
Working copy (@) : mzxutzyn3a50ae8d(no description set)
Parent commit (@-): rovxnrwu00fb8673main | Start the timer app
3. Describe it whenever you like
A commit can get its message at any point: before the work, after it, or five rewrites later. Nothing forces you to name a thing before you understand it.
$jj describe -m "Add pause button"
Working copy (@) now at: mzxutzynd085b8cf Add pause button
Parent commit (@-) : rovxnrwu00fb8673main | Start the timer app
Changes and commits
4. Two IDs, two jobs
Every commit carries two IDs. The change ID, in letters, names the piece of work and never changes. The commit ID, in hex, names one exact snapshot, so every rewrite gets a new one. The pale shells trailing behind the orb are the earlier snapshots of this same change. Nothing was overwritten.
$jj evolog
@ mzxutzynd085b8cf Add pause button
○ mzxutzyn3a50ae8d(no description set)
○ mzxutzyn1e89af9e(empty)(no description set)
5. Start the next change
jj new starts a fresh, empty change on top. The one below is done for now, but it is never locked. You can come back to it at any time.
$jj new
Working copy (@) now at: pnqmxkrqa099bf4f(empty)(no description set)
Edit README.md, then describe the change. jj snapshots your files first and sets the message second: two operations from one command, and two shells left behind.
$jj describe -m "Document the pause button"
Working copy (@) now at: pnqmxkrq267b55cb Document the pause button
You spot a bug in the pause button. Go back to that change. There is no stash and no detached state to worry about: @ simply moves there, and the work above it stays where it is.
$jj edit mz
Working copy (@) now at: mzxutzynd085b8cf Add pause button
Parent commit (@-) : rovxnrwu00fb8673main | Start the timer app
8. What sits above follows along
Fix app.js. The pause change gets a new snapshot, and jj rebases the change above it automatically. Both commit IDs are new. Both change IDs are the same as before.
$jj st
Rebased 1 descendant commits onto updated working copy
Working copy changes:
M app.js
M style.css
Working copy (@) : mzxutzyn584e9fd7 Add pause button
Parent commit (@-): rovxnrwu00fb8673main | Start the timer app
9. Return to the top
To carry on where you left off, start a new change on the newest one.
$jj new pn
Working copy (@) now at: tonqoqqvecdf3f48(empty)(no description set)
Parent commit (@-) : pnqmxkrq6be8a2b6 Document the pause button
Move work between commits
10. A fix that belongs elsewhere
You notice a typo in the README. The fix belongs in the change below, not in a commit of its own. Make the edit anyway, right where you are.
$jj st
Working copy changes:
M README.md
Working copy (@) : tonqoqqv86ed8e47(no description set)
Parent commit (@-): pnqmxkrq6be8a2b6 Document the pause button
11. Squash it down
jj squash moves what is in @ into its parent. Watch the block travel. @ is empty again and ready for the next thing. jj split does the reverse, and jj squash --into can send the work to any commit.
$jj squash
Working copy (@) now at: ystrxnvof116cb47(empty)(no description set)
Parent commit (@-) : pnqmxkrqe494cb07 Document the pause button
A rebase always finishes
12. Meanwhile, on main
A teammate pushed to main. After a fetch, main has moved up, and your two changes now hang off the old spot.
$jj git fetch
bookmark: main@origin [updated] tracked
13. Move the stack, conflicts and all
Move your work onto the new main. The teammate changed the same lines of app.js, so there is a conflict. In jj the rebase still finishes. The conflict is recorded inside the commit, shown in red, and everything above carries it until it is fixed.
pnqmxkrqddcbdabb(conflict) Document the pause button
mzxutzyn50e4245c(conflict) Add pause button
Hint: To resolve the conflicts, start by creating a commit
on top of the first conflicted commit: jj new mz
Conflicts can wait
14. Fix it when you are ready
Nothing is blocked. When you choose to deal with it, start a change on top of the first red commit. The empty @ you leave behind held nothing, so jj drops it for you.
$jj new mz
Working copy (@) now at: kynswswma16fb8b5(conflict)(empty)(no description set)
Want to try something else? Start a change on main. A second line of work grows beside the first. It has no branch name and does not need one.
$jj new main -m "Try a dark theme"
Working copy (@) now at: wnxuyullc8b69316(empty) Try a dark theme
Parent commit (@-) : oxwwlzzkb48186c2main | Rename start to play
18. Both lines stay in view
Edit style.css. Both lines of work are visible in jj log at once, and you move between them with jj edit or jj new. There is no “current branch” to switch.
$jj st
Working copy changes:
M style.css
Working copy (@) : wnxuyull0a6407cd Try a dark theme
Parent commit (@-): oxwwlzzkb48186c2main | Rename start to play
Bookmarks and Git
19. A name, only when you need one
Git needs a branch name to receive a push. jj calls these bookmarks: plain labels on a commit. A bookmark does not creep forward when you add commits above it, but it does follow its commit through every rewrite.
$jj bookmark set pause-button -r pn
Created 1 bookmarks pointing to pnqmxkrqaa24f3e0pause-button | Document the pause button
20. Push to Git
Underneath, this is an ordinary Git repository. Push the bookmark and your teammates see a normal branch. They never need to know you used jj.
$jj git push --bookmark pause-button
Changes to push to origin:
Add bookmark pause-button to aa24f3e0
Nothing is lost
21. The operation log
Every command you ran was recorded as an operation. Each sheet reaching back is the whole repository as it stood after one command. The pale shells you have been seeing live on those sheets.
$jj op log
@ 0970062abccc push bookmark pause-button to git remote origin
○ 4c5c09937ae4 point bookmark pause-button to commit aa24f3e0
○ 8bff5ddcebb5 snapshot working copy
○ 9bd033672750 new empty commit
○ 0b0f8f96c45a squash commits into 50e4245c
○ 1a187adb9c8c snapshot working copy
22. A mistake
Now you throw away the dark theme, and a minute later you wish you had not.
$jj abandon @
Abandoned 1 commits:
wnxuyull0a6407cd Try a dark theme
Working copy (@) now at: nstvskou8ee8fe5e(empty)(no description set)
Parent commit (@-) : oxwwlzzkb48186c2main | Rename start to play
23. Undo
jj undo puts the repository back as it was one sheet ago. The dark theme returns, exactly as you left it. The undo is itself a new operation, so even that can be undone.
$jj undo
Restored to operation: 0970062abccc push bookmark pause-button to git remote origin
Working copy (@) now at: wnxuyull0a6407cd Try a dark theme
Parent commit (@-) : oxwwlzzkb48186c2main | Rename start to play
24. The shape of jj
The working copy is a commit, snapshotted for you.
A change keeps its ID while its commits come and go.
Rewrite anything, and what sits above follows.
Conflicts are saved in commits and can wait.
Every command is an operation, and jj undo walks back.