Jujutsu version control

jj

gg

hg

wait…

Hello! Jujutsu, or jj, is a newer version control system that can replace Git and these were my private notes as I’m learning it. Decided to publish them here.

Someone said that

AI is a version control problem

and I very much believe this. I don’t know if jj is “better” than git but it’s worth exploring.

Most who use git will at some point ask themselves: “Why so complicated? Is it me? Is it git? Well, both. Git suffer from decades of history. Git can not just change a command or improve how it works, because it is used everywhere. In software we usually avoid change when possible.

Jujutsu has a unique position in that it’s is, or was, not used anywhere. It can learn from years and years of millions of people working with git, mercurial and others daily. And it can give us a fresh take. This article explores Jujutsu from a beginner’s perspective and my aim is to be able to use it for myself to start with.

Since jj uses Git as its backend, you can try it on existing repositories with minimal risk.

To start if you already have a repo:

jj git clone <repo-url>

or

jj git init --git-repo <path>

Coming from git you will be used to working with commits. In Jujutsu the fundamental change is called a revision and importantly new revisions are AUTOMATICALLY created as files are changed. You do not need to git add anything. As you use jj log you can observe the change id staying consistent and the revision id updating with every file change.

I found these references:

and here’s my version:

The rough guide to Jujutsu (jj)

These are my (edited) notes as I’m trying to understand how jj works. This guide is aimed at people with experience with version control systems, particularly git.

Working copy

First steps

jj git clone <url>  # → start on fresh working copy `@`, already a new change
# edit files
jj describe -m "Add login form"  # → refine current change (same ID, new revision)
jj new  # → finish current change, start fresh one on top

Everyday flow

See where you are:

jj status # or jj st

# @- is the parent change, @ is the current change
jj log -r @-
jj log -r 'main..@'
jj show          # show changes in current revision
jj show -r @-    # show changes in parent revision

Pause current work to start something else:

jj new @-          # create new change based on parent, keeping current work
# work on urgent fix
jj new             # back to a fresh change when done

Discard unwanted work:

jj abandon         # discard current revision (work is lost)
jj abandon -r <id> # discard specific revision

Move your working copy to a different change:

jj edit -r main        # go to main (like git checkout main)
jj edit -r @-          # go to parent change
jj edit -r <change-id> # go to specific change

Restore specific files from other revisions:

jj restore --from main file.txt         # restore file from main
jj restore --from @- --to @ file.txt    # restore file from parent to current
jj restore --from @- .                  # restore all files from parent

Selective changes

jj split -i        # split working copy into two changes (interactive hunks)
jj squash -i       # move hunks into parent change
jj squash <file>   # move whole file into parent

This replaces Git’s git add -p and git commit --amend -p workflow. Note: jj split is subtractive - you remove what you don’t want in the first commit (opposite of Git’s additive staging).

Reshape history

jj squash           # combine changes
jj diffedit         # edit an earlier change

Conflicts

Unlike git, jj can save conflicts directly in commits. You don’t have to fix them immediately. The <<<<<<< markers in your files are just how jj shows you the conflict - the real conflict data is stored separately.

# Option 1: Fix conflicts in a new commit
jj new <conflicted-commit>
# edit files to remove conflict markers
jj squash                   # merge the fix back

# Option 2: Use a merge tool
jj resolve

Benefits: you can rebase or merge commits that still have conflicts. Other commits will update automatically even when conflicts exist.

Undo mistakes

jj op log             # see all repository operations
jj undo               # undo last operation
jj obslog -r <change> # see how a specific change evolved over time

Describe vs new

In a fresh repo, you usually jj describe first. Use jj new only when moving on to the next change. Changes have stable IDs that persist through all edits and descriptions.

Bookmarks (branches)

In jj you won’t deal with branches as you know them from Git. Instead you create bookmarks when you want to share changes. You can work on anonymous changes until you’re ready to sync:

jj bookmark create feature-name    # create bookmark at current change
jj git push -c feature-name        # push and create remote bookmark

Or let jj auto-generate bookmark names when pushing:

jj git push -c @                   # auto-generates bookmark name

Sync with remotes

jj git fetch                        # updates local view of remote bookmarks
jj rebase -d main                   # restructures your change to sit on top of main
jj bookmark create feature-name     # create bookmark for sharing
jj git push -c feature-name         # push new bookmark (-c = create)

Merging into main (fast-forward)

# After rebasing onto main, move the main bookmark to your change
jj bookmark set main -r @           # moves bookmark pointer (doesn't change graph)
jj git push --bookmark main         # pushes bookmark movement to remote

Revset flexibility: Use change IDs (nrtvnxuk), revision IDs (fea9ae77), bookmarks (main, feature-name), or symbols (@, @-) interchangeably with -r. Jj shows unique prefixes in output - type just the highlighted characters.

In jj, you don’t “stage then commit.” You work inside a change, refine it with describe, splitting and squashing as needed. Use new only when you’re ready for the next change.

flowchart TD

subgraph Change_A["Change A (stable ID)"]
  R1["Revision A1 (first working copy)"]
  R2["Revision A2 (after jj describe)"]
  R3["Revision A3 (after jj describe again)"]
end

subgraph Change_B["Change B (new stable ID)"]
  R4["Revision B1 (jj new creates this)"]
end

R1 --> R2 --> R3 --> R4