jj in 3D

Jujutsu version control, one command at a time

jj in 3D

Jujutsu version control, one command at a time

A small repository drawn in 3D: a column of commits rising from the root, three of them red with conflicts, and pale rings behind them where their older versions are kept
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
@ mzxutzyn 1e89af9e
│ (empty) (no description set)
◆ rovxnrwu 00fb8673 main
│ 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 (@) : mzxutzyn 3a50ae8d (no description set)
Parent commit (@-): rovxnrwu 00fb8673 main | 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: mzxutzyn d085b8cf Add pause button
Parent commit (@-) : rovxnrwu 00fb8673 main | 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
@ mzxutzyn d085b8cf Add pause button
○ mzxutzyn 3a50ae8d (no description set)
○ mzxutzyn 1e89af9e (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: pnqmxkrq a099bf4f (empty) (no description set)
Parent commit (@-) : mzxutzyn d085b8cf Add pause button

6. Work, then describe

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: pnqmxkrq 267b55cb Document the pause button
Parent commit (@-) : mzxutzyn d085b8cf Add pause button

Edit anywhere

7. Go back to an older change

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: mzxutzyn d085b8cf Add pause button
Parent commit (@-) : rovxnrwu 00fb8673 main | 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 (@) : mzxutzyn 584e9fd7 Add pause button
Parent commit (@-): rovxnrwu 00fb8673 main | 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: tonqoqqv ecdf3f48 (empty) (no description set)
Parent commit (@-) : pnqmxkrq 6be8a2b6 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 (@) : tonqoqqv 86ed8e47 (no description set)
Parent commit (@-): pnqmxkrq 6be8a2b6 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: ystrxnvo f116cb47 (empty) (no description set)
Parent commit (@-) : pnqmxkrq e494cb07 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.
$ jj rebase -s mz -o main
Rebased 3 commits to destination
New conflicts appeared in 3 commits:
ystrxnvo 46a5379a (conflict) (empty) (no description set)
pnqmxkrq ddcbdabb (conflict) Document the pause button
mzxutzyn 50e4245c (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: kynswswm a16fb8b5 (conflict) (empty) (no description set)
Parent commit (@-) : mzxutzyn 50e4245c (conflict) Add pause button

15. Resolve in a commit of its own

Edit the conflict markers in app.js, or run jj resolve. Your new change is clean. The red commits are still waiting for the fix to reach them.
$ jj st
Working copy changes:
M app.js
Working copy (@) : kynswswm a48f48b4 (no description set)
Parent commit (@-): mzxutzyn 50e4245c (conflict) Add pause button

16. Squash the fix into place

Squash the fix into the conflicted commit. It turns clean, jj rebases the change above it, and that one turns clean too.
$ jj squash
Rebased 1 descendant commits
Working copy (@) now at: uyvkyxvo b8d425ba (empty) (no description set)
Parent commit (@-) : mzxutzyn 999acbed Add pause button

Side work needs no name

17. Try an idea on the side

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: wnxuyull c8b69316 (empty) Try a dark theme
Parent commit (@-) : oxwwlzzk b48186c2 main | 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 (@) : wnxuyull 0a6407cd Try a dark theme
Parent commit (@-): oxwwlzzk b48186c2 main | 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 pnqmxkrq aa24f3e0 pause-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:
wnxuyull 0a6407cd Try a dark theme
Working copy (@) now at: nstvskou 8ee8fe5e (empty) (no description set)
Parent commit (@-) : oxwwlzzk b48186c2 main | 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: wnxuyull 0a6407cd Try a dark theme
Parent commit (@-) : oxwwlzzk b48186c2 main | 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.
Drag the picture to look around. To read more: the jj documentation, its comparison with Git, From Git to jj, and a jj primer.