Jujutsu Primer

Hacker News by 29 min read 11x views
Jujutsu Primer

Share Post

This guide is a brief(ish) introduction to the Jujutsu (jj) type authority scheme (VCS) for person acquainted alongside Git.

Why try Jujutsu?

jj provides primitives for type authority that are uncomplicated to learn, but elegantly create into mighty workflows. Features akin automatic rebase and native undo soften the keen edges of Git. Eventually, you’ll organically detect new mighty workflows that would be too cumbersome to attempt alongside most another VCS tools.

If you activity in a Git repository, you can try it today. Jujutsu and Git can be used side-by-side in the identical repository, so you can try out jj on a git repo on your own, without completely ejecting from git.

Personally, I think jj considerably boosts my effectiveness, since it allows me to keep VCS bookkeeping out of my operating memory. Automatic rebasing additionally makes stacked diff workflows fairly easy, and reduces thrashing of my operating memory. It’s additionally fair a fun tool to use.

Installing jj

Official facility instructions are here, but current are a few average methods:

brew instal jj  pacman -S jujutsu  nix-shell -p jujutsu  cargo install --locked --bin jj jj-cli 

Setup and configuration

In an existing git repository, run:

jj git init 

From current on, jj and git repo province volition be synchronized automatically.

To set your person particulars globally, run commands akin these:

jj config set --user user.name "Some One" jj config set --user user.email "[email protected]" 

You can edit jj’s TOML configuration for your person in an publishing company with:

jj config edit --user 

In supplement to the --user scope, jj config additionally has --repo and --workspace scopes. View the merged config with:

jj config list 

Commits and changes

A commit, additionally called a revision, is basically the identical item as a git commit. It represents a snapshot of repository province that descends from one or additional genitor repository snapshots. It is frequently visualized as a diff against a distinctive genitor commit, or in the case of a merge commit, the diff against multiple genitor commits formerly merged.

When using a Git repo backend, the jj commit ID is the identical as the git commit ID: a hash formatted as a hex string. In the output of jj log below, the hex hashes 2bea5e3d and 849165bc on the correct are commit IDs.

$ jj log @ k [email protected] 2026-11-15 12:17:12 8 │ (empty) (no clarification set) ◆ r [email protected] 2026-11-15 12:10:46 main 2 │ Adjust config ~ 

The IDs on the remaining hand flank (royxmykx and kpqxywon) are change IDs, which are stable identifiers for logical changes as they physically develop complete time. We’ll conversation these additional in the next section.

Commit IDs and alter IDs can be referenced in shorthand alongside an unambiguous (unique) prefix. jj helpfully highlights the shortest distinctive prefix of most IDs to create it uncomplicated to category them manually. For example, instead of copying and pasting kpqxywon, we can category in a prefix, downward to the shortest distinctive prefix k.

We can inspect the commit 2bea5e3d alongside jj show, using its abbreviated prefix 2.

$ jj display 2 Commit ID: 2bea5e3d1992a60ba9ee52c6ce37c55adba9e8fb Change ID: royxmykxtrkrqppotnrvutxlvrvqyxmy Bookmarks: main main@git main@origin Author : Ethan Lowman <[email protected]> (2026-11-15 12:10:46) Committer: Ethan Lowman <[email protected]> (2026-11-15 12:10:46) Adjust config diff --git a/config.py b/config.py index 7366a4e31d..174ffea06b 100644 --- a/config.py +++ b/config.py @@ -1,1 +1,1 @@ -DEFAULT_LIMIT = 10 +DEFAULT_LIMIT = 20 

Many folks configure a tradition diff formatter, akin Delta. See configuration docs if you’re interested.

Creating & evolving changes

Let’s obtain another appearance at our commit graph:

$ jj log @ k [email protected] 2026-11-15 12:17:12 8 │ (empty) (no clarification set) ◆ r [email protected] 2026-11-15 12:10:46 main 2 │ Adjust config ~ 

On commit 849165bc, you’ll see the sign @ on the chart node. This represents a snapshot of our working copy, or the code we have really checked out in our local directory. We can inspect this particular commit pointer in a assortment of ways:

jj display shows commit particulars and a diff, which is bare here.

$ jj show Commit ID: 849165bca19639dbd6ccb53e8c1340e78c36d59a Change ID: kpqxywonksrltlrkyqukqqsxpltznztk Author : Ethan Lowman <[email protected]> (2026-11-15 12:17:12) Committer: Ethan Lowman <[email protected]> (2026-11-15 12:17:12)  (no clarification set) 

jj position shows repo province alongside diff stats.

$ jj status The operating copy has no changes. Working copy (@) : k 8 (empty) (no clarification set) Parent commit (@-): r 2 mainAdjust config 

jj diff plant much akin git diff. Its output is bare here, since there are no changes in the current operating copy related to the genitor commit.

This output isn’t extremely interesting, since @ has no changes. Let’s create an example alter to see what happens. If we edit main.py and rerun jj show, we see this:

$ jj show Commit ID: 66b59f20c534705cfb753c722222290e9185b22c Change ID: kpqxywonksrltlrkyqukqqsxpltznztk Author : Ethan Lowman <[email protected]> (2026-11-15 12:26:43) Committer: Ethan Lowman <[email protected]> (2026-11-15 12:26:43)  (no clarification set) diff --git a/main.py b/main.py new document manner 100644 index 0000000000..c74cd2e0e0 --- /dev/null +++ b/main.py @@ -0,0 +1,2 @@ def my_new_feature(): +def my_new_feature(): + pass 
$ jj log @ k [email protected] 2026-11-15 12:26:43 6 │ (no clarification set) ◆ r [email protected] 2026-11-15 12:10:46 main 2 │ Adjust config ~ 

You’ll notice multiple things have changed. The operating copy has been automatically committed, and @ is no longer marked (empty). The new commit ID for @ is 66b59f20, since we’ve added changes, but the alter ID for 66b59f20 is motionless kpqxywon. jj has no staging area akin in git, so we don’t have to manually add files. When we run a jj command to inspect or modify repo province following editing files, jj automatically snapshots the operating copy as a new bodily commit for the applicable logical change.

Let’s provision this alter a clarification (also called a commit message). We can either run jj desc, which opens an editor, or provision it immediately alongside -m.

$ jj desc -m "Implement the feature" Working copy (@) now at: k 6 Implement the feature Parent commit (@-) : r 2 mainAdjust config 

Notice again that the commit ID has changed, since the hash covers the commit message, but the alter ID has remained stable.

Now, let’s say we’re prepared to use this new feature, and we desire to arrange that alter in a distinct commit. We can create a new commit alongside jj new:

$ jj new Working copy (@) now at: n 6c (empty) (no clarification set) Parent commit (@-) : k 6b Implement the feature 
$ jj log @ n [email protected] 2026-11-15 12:35:49 6c │ (empty) (no clarification set) ○ k [email protected] 2026-11-15 12:33:23 6b │ Implement the feature ◆ r [email protected] 2026-11-15 12:10:46 main 2 │ Adjust config ~ 

We’ve created an bare alter nlrtlrxv on top of kpqxywon. jj position reflects that we are editing this new revision which does not yet differ from its parent.

$ jj status The operating copy has no changes. Working copy (@) : n 6c (empty) (no clarification set) Parent commit (@-): k 6b Implement the feature 

jj commit is a shorthand for this average jj desc and jj new combo. Let’s create another alter to use our new feature, and commit it.

$ jj commit -m "Use the feature" Working copy (@) now at: q 9 (empty) (no clarification set) Parent commit (@-) : n e Use the feature 
$ jj log @ q [email protected] 2026-11-15 12:41:30 9 │ (empty) (no clarification set) ○ n [email protected] 2026-11-15 12:41:30 e │ Use the feature ○ k [email protected] 2026-11-15 12:33:23 6 │ Implement the feature ◆ r [email protected] 2026-11-15 12:10:46 main 2 │ Adjust config ~ 

To inspect the commit we fair created (n), we can no longer use the naked jj show, which defaults to showing @. We have to continue the revision we desire to inspect:

$ jj display n Commit ID: e1b066782aa1a565c1e5d38ef27a308aa58e7e4c Change ID: nlrtlrxvuuskxprvtuznquqzqzzwvnzk Author : Ethan Lowman <[email protected]> (2026-11-15 12:41:30) Committer: Ethan Lowman <[email protected]> (2026-11-15 12:41:30) Use the feature diff --git a/main.py b/main.py index c74cd2e0e0..0714ec450b 100644 --- a/main.py +++ b/main.py @@ -1,2 +1,4 @@ def my_new_feature(): def my_new_feature(): pass + +do_something(my_new_feature()) 

We can depict bare commits to document intent before starting work. Let’s create a new commit on top of k to prompt ourselves that we need to document the feature.

$ jj new k -m "Document the feature" Working copy (@) now at: q 4 (empty) Document the feature Parent commit (@-) : k 6 Implement the feature Added 0 files, modified 1 files, removed 0 files 

A distinct jj desc would additionally activity fair fine alternatively of the -m emblem on jj new. Here’s the current commit graph:

$ jj log @ q [email protected] 2026-11-15 12:46:35 4 │ (empty) Document the feature │ ○ n [email protected] 2026-11-15 12:41:30 e ├─┘ Use the feature ○ k [email protected] 2026-11-15 12:33:23 6 │ Implement the feature ◆ r [email protected] 2026-11-15 12:10:46 main 2 │ Adjust config ~ 

Note how we’ve created branching commits without creating a named branch. This highlights a important difference between jj’s branchless example and git’s branch-centric example of organizing activity streams. Instead of juggling your work-in-progress on branches, you activity on a chart of commits. Once prepared to share, you shove branches to a Git forge from your commit chart (more on that later).

Revsets

A revset, an idea borrowed from Mercurial, is an expression that selects a set of revisions from the commit graph. Most jj commands obtain revsets in their arguments. When we ran jj new k, the disagreement k was really a trivial revset that resolved to the sole alter alongside ID kpqxywon. The jj log command has an -r <REVSET> emblem that we can use to preview a revset. Some demonstrative examples follow.

Parent of @:

$ jj log -r @- ○ k [email protected] 2026-11-15 12:33:23 6 │ Implement the feature ~ 

Grandchildren of r:

$ jj log -r r++ @ q [email protected] 2026-11-15 12:51:45 5 │ Document the feature ~ ○ n [email protected] 2026-11-15 12:41:30 e │ Use the feature ~ 

Commits between r and @, inclusive:

$ jj log -r r::@ @ q [email protected] 2026-11-15 12:51:45 5 │ Document the feature ○ k [email protected] 2026-11-15 12:33:23 6 │ Implement the feature ◆ r [email protected] 2026-11-15 12:10:46 main 2 │ Adjust config ~ 

Commit k and all descendants:

$ jj log -r k:: @ q [email protected] 2026-11-15 12:51:45 5 │ Document the feature │ ○ n [email protected] 2026-11-15 12:41:30 e ├─┘ Use the feature ○ k [email protected] 2026-11-15 12:33:23 6 │ Implement the feature ~ 

Commits authored by [email protected] that additionally have ID k or q:

$ jj log -r 'author("[email protected]") & (k | q)' @ q [email protected] 2026-11-15 12:51:45 5 │ Document the feature ○ k [email protected] 2026-11-15 12:33:23 6 │ Implement the feature ~ 

I’ll defer to the authoritative records for exhaustive detail. The Revsets language specification is effortlessly my most referenced jj records page, so I would propose skimming it to see what’s possible.

Let’s say in the way of documenting our characteristic in qwyusntz we realized we made a error in the implementation in genitor alter kpqxywon. We don’t need to manually commit or stash changes to toggle tasks. We merely toggle our operating copy to kpqxywon alongside jj edit:

$ jj edit k Working copy (@) now at: k 6 Implement the feature Parent commit (@-) : r 2 mainAdjust config Added 0 files, modified 0 files, removed 1 files 

Our operating copy formerly again shows the changes from kpqxywon.

$ jj show Commit ID: 6b89ffb2a250f622a8638145d65fe8c9bb308dbf Change ID: kpqxywonksrltlrkyqukqqsxpltznztk Author : Ethan Lowman <[email protected]> (2026-11-15 12:26:43) Committer: Ethan Lowman <[email protected]> (2026-11-15 12:33:23) Implement the feature diff --git a/main.py b/main.py new document manner 100644 index 0000000000..c74cd2e0e0 --- /dev/null +++ b/main.py @@ -0,0 +1,2 @@ def my_new_feature(): +def my_new_feature(): + pass 

jj hasn’t misplaced track of the changes complete our operating copy, including our most latest edits to q:

$ jj log ○ q [email protected] 2026-11-15 12:51:45 5 │ Document the feature │ ○ n [email protected] 2026-11-15 12:41:30 e ├─┘ Use the feature @ k [email protected] 2026-11-15 12:33:23 6 │ Implement the feature ◆ r [email protected] 2026-11-15 12:10:46 main 2 │ Adjust config ~ 

Instead of switching commits alongside jj edit k, we could have run jj edit @-. The revset @- is evaluated before switching the operating copy, so this moves to the genitor commit. The built-in commands jj next [--edit] and jj prev [--edit] provision another way to move up and downward a stack of commits.

Automatic rebasing

If we edit records in the operating copy, the descendant commits volition be automatically rebased upon the next jj invocation. For example, if we edit my_new_feature’s implementation in main.py and afterward run jj log, we’ll see that changes k, n, and q all get new commit IDs. jj additionally tells us that it performed a rebase.

$ jj log Rebased 2 descendant commits onto updated operating copy. ○ q [email protected] 2026-11-15 13:03:41 7 │ Document the feature │ ○ n [email protected] 2026-11-15 13:03:41 4 ├─┘ Use the feature @ k [email protected] 2026-11-15 13:03:41 d │ Implement the feature ◆ r [email protected] 2026-11-15 12:10:46 main 2 │ Adjust config ~ 

Handling conflicts

If the automatic rebase happened to logic merge conflicts, jj doesn’t necessitate us to fix them immediately, akin git rebase would. Instead, jj records that the commit is conflicted and lets you transport on alongside your current task. This is massively helpful to decrease mental environment switching, as your stacked commits develop additional complex.

$ jj log Rebased 2 descendant commits onto updated operating copy. ○ q [email protected] 2026-11-15 13:05:35 b │ Document the feature │ × n [email protected] 2026-11-15 13:05:35 e (conflict) ├─┘ Use the feature @ k [email protected] 2026-11-15 13:05:35 c │ Implement the feature ◆ r [email protected] 2026-11-15 12:10:46 main 2 │ Adjust config ~ 

To perspective the conflicts, we can edit the conflicted commit…

$ jj edit n Working copy (@) now at: n e (conflict) Use the feature Parent commit (@-) : k c Implement the feature Added 0 files, modified 1 files, removed 0 files Warning: There are unresolved conflicts at these paths: main.py 2-sided conflict 

And inspect main.py.

def my_new_feature():  print("Hello from the new feature!") <<<<<<< battle 1 of 1 %%%%%%% diff from: kpqxywon d9f35831 "Implement the feature" (parents of rebased revision) \\\\\\\ to: kpqxywon c501c0bd "Implement the feature" (rebase destination) - pass + come back 42 +++++++ nlrtlrxv 41a43a84 "Use the feature" (rebased revision)  pass  do_something(my_new_feature()) >>>>>>> battle 1 of 1 ends  

In a content editor, we can determine these conflicts, and the next period we run any jj command, we’ll see that jj has marked the commit as unconflicted:

$ jj status Working copy changes: M main.py Working copy (@) : n 3 Use the feature Parent commit (@-): k c Implement the feature 

Undo and the op log

Let’s say we made a error in that battle resolution, and we desire to undo it. In git, undoing an action, if it’s equal possible, is frequently complicated. In jj, we can continually run jj undo:

$ jj undo Undid operation: 35beb0741f17 (2026-11-15 13:08:39) snapshot operating copy Restored to operation: f134ca987b59 (2026-11-15 13:07:18) edit commit e562bff4876f3ea76248c3f730e9e74d3e28e8a0 Working copy (@) now at: n e (conflict) Use the feature Parent commit (@-) : k c Implement the feature Added 0 files, modified 1 files, removed 0 files Warning: There are unresolved conflicts at these paths: main.py 2-sided conflict New conflicts appeared in 1 commits: n e (conflict) Use the feature Hint: To determine the conflicts, commencement by creating a commit on top of the conflicted commit: jj new n Then use `jj resolve`, or edit the battle markers in the document directly. Once the conflicts are resolved, you can inspect the outcome alongside `jj diff`. Then run `jj squash` to move the resolution into the conflicted commit. 

More generally, jj maintains a former of all actions in jj op log. We can inspect this log and jj op reconstruct to a item in that history, or jj op revert an idiosyncratic operation. If the jj undo itself was a mistake, we can jj redo.

The Hint in the output complete is a bit of a spoiler for our next topic, the squash workflow.

Squash workflow

Editing commits that have descendants can sometimes awareness sketchy. If you’re iterating on a ample diff that has remaining your operating memory, it would be nice to distinct your new changes from the existing diff. For example, we power akin to inspect the diff that resolves a rebase battle in isolation.

Let’s prosecute the instructions from the complete output. We archetypal create a new commit on top of the conflicted commit:

$ jj new n Working copy (@) now at: w b8 (conflict) (empty) (no clarification set) Parent commit (@-) : n e (conflict) Use the feature Warning: There are unresolved conflicts at these paths: main.py 2-sided conflict 
$ jj log -r n:: @ w [email protected] 2026-11-15 13:11:44 b8 (conflict) │ (empty) (no clarification set) × n [email protected] 2026-11-15 13:05:35 e (conflict) │ Use the feature ~ 

Now we can determine the conflicts in main.py in our editor, and rerun jj log:

$ jj log -r n:: @ w [email protected] 2026-11-15 13:14:12 9 │ (no clarification set) × n [email protected] 2026-11-15 13:05:35 e (conflict) │ Use the feature ~ 

We can inspect the diff in @ if we like, and whenever we’re blessed alongside the battle resolution, we can squash it into the genitor commit:

$ jj squash Working copy (@) now at: v f (empty) (no clarification set) Parent commit (@-) : n 7 Use the feature Existing conflicts were resolved or abandoned from 1 commits. 
$ jj log -r n:: @ v [email protected] 2026-11-15 13:15:39 f │ (empty) (no clarification set) ○ n [email protected] 2026-11-15 13:15:39 7 │ Use the feature ~ 

The battle is now resolved, and we can continue our work.

More commit chart operations

One of the mighty qualities of jj is that it makes diffs malleable akin clay. With automatic rebase and the confidence inspired by jj undo, we can move, combine, drop, and divided diffs alongside ease.

Let’s try a few operations on our current commit graph. Here’s the starting point.

$ jj log @ v [email protected] 2026-11-15 13:15:39 f │ (empty) (no clarification set) ○ n [email protected] 2026-11-15 13:15:39 7 │ Use the feature │ ○ q [email protected] 2026-11-15 13:05:35 b ├─┘ Document the feature ○ k [email protected] 2026-11-15 13:05:35 c │ Implement the feature ◆ r [email protected] 2026-11-15 12:10:46 main 2 │ Adjust config ~ 

Rebase

Let’s use jj rebase to coerce our branching commit chart into a linear history. Let’s say the records commit (q) should go between the implementation (k) and the use (n). We could accomplish this by moving nlrtlrxv (and its bare descendant) on top of qwyusntz:

$ jj rebase -s n -o q Rebased 2 commits to destination. Working copy (@) now at: v 0 (empty) (no clarification set) Parent commit (@-) : n 9 Use the feature Added 1 files, modified 0 files, removed 0 files 
$ jj log @ v [email protected] 2026-11-15 13:20:18 0 │ (empty) (no clarification set) ○ n [email protected] 2026-11-15 13:20:18 9 │ Use the feature ○ q [email protected] 2026-11-15 13:05:35 b │ Document the feature ○ k [email protected] 2026-11-15 13:05:35 c │ Implement the feature ◆ r [email protected] 2026-11-15 12:10:46 main 2 │ Adjust config ~ 

Another way to accomplish the identical consequence would be to use jj rebase -r q --before n. Many jj commands have multiple ways to define revsets. jj rebase --help documents these well.

Since arguments to jj rebase flags are all revsets, we can compose a revset that selects a sequence of commits or commit subgraph, and move it elsewhere in the graph.

If we wanted to insert a commit below k, the most straightforward way is jj new --before k, but for display purposes, we could alternatively create a new commit on top of r and rebase k:: on top:

$ jj new r -m "Prepare for the feature" Working copy (@) now at: w be (empty) Prepare for the feature Parent commit (@-) : r 2 mainAdjust config Added 0 files, modified 0 files, removed 2 files 
$ jj log @ w [email protected] 2026-11-15 13:23:29 be │ (empty) Prepare for the feature │ ○ n [email protected] 2026-11-15 13:20:18 9 │ │ Use the feature │ ○ q [email protected] 2026-11-15 13:05:35 b9 │ │ Document the feature │ ○ k [email protected] 2026-11-15 13:05:35 c ├─┘ Implement the feature ◆ r [email protected] 2026-11-15 12:10:46 main 2 │ Adjust config ~ 
$ jj rebase -s k -o w Rebased 3 commits to destination. 
$ jj log ○ n [email protected] 2026-11-15 13:28:02 c │ Use the feature ○ q [email protected] 2026-11-15 13:28:02 e │ Document the feature ○ k [email protected] 2026-11-15 13:28:02 7 │ Implement the feature @ w [email protected] 2026-11-15 13:23:29 b │ (empty) Prepare for the feature ◆ r [email protected] 2026-11-15 12:10:46 main 2 │ Adjust config ~ 

If you bask using TUIs, jj arrange provides a commit chart publishing company akin to git rebase -i for reordering commits.

Squash

If we decided records have to be in the identical commit as implementation, we can squash:

$ jj squash --from q --into k Rebased 1 descendant commits. 

jj volition open an publishing company and provision us a chance to compose a blended commit message.

$ jj log ○ n [email protected] 2026-11-15 13:31:30 c │ Use the feature ○ k [email protected] 2026-11-15 13:31:30 b9 │ Implement and document the feature @ w [email protected] 2026-11-15 13:23:29 be │ (empty) Prepare for the feature ◆ r [email protected] 2026-11-15 12:10:46 main 2 │ Adjust config ~ 

Abandon

To autumn a commit from the graph, we can use jj abandon. Let’s autumn the preparedness commit:

$ jj forsake w Abandoned 1 commits: w be (empty) Prepare for the feature Rebased 2 descendant commits onto parents of abandoned commits. Working copy (@) now at: x d4 (empty) (no clarification set) Parent commit (@-) : r 2 mainAdjust config 
$ jj log @ x [email protected] 2026-11-15 13:33:49 d4 │ (empty) (no clarification set) │ ○ n [email protected] 2026-11-15 13:33:49 b │ │ Use the feature │ ○ k [email protected] 2026-11-15 13:33:49 df ├─┘ Implement and document the feature ◆ r [email protected] 2026-11-15 12:10:46 main 2 │ Adjust config ~ 

To forsake parts of a commit (hunks or changes to entire files), we can use the jj diffedit TUI (see docs).

Split

The jj divided TUI allows us to obtain a commit and divided it into two successive commits by selecting which records or hunks should go in the first. Let’s use it to divided up implementation and records again alongside jj divided -r k:

The jj-hunk project provides a method to automate commit splitting. If you are so inclined, agents are fairly fine at using this tool to divided up commits into a sequence of smaller changes for easier review.

Bookmarks and Git branches

jj does not have a native idea of a branch, but it does have a primitive called bookmarks that map to Git branches. When we need to manipulate Git branches, we do it by way of bookmarks.

You can go beautiful far using Git without realizing this, but a Git branch is fair a pointer to a commit. jj explicitly models bookmarks this way. jj bookmarks are basically a named tag attached to a commit that we can move about as we modify our commit graph, and shove to/pull from a remote.

We’ll conversation a few essential workflows about Git branches below, but you can discover a additional complete guide in the jj docs on Working alongside GitHub.

Pushing a new branch

Assuming we initialized jj in a git repository that has remotes, we should have several output for jj git distant list.

$ jj git distant list origin [email protected]:ethanal/example.git 

Since jj is branchless, the commits we’ve created locally don’t have a branch name. Luckily, jj doesn’t necessitate us to choice one, and generates one for us. Generated branch names liberated you from thinking of a distinctive branch name so you can alternatively concentration on penning a fine commit communication (usually the additional durable descriptor of a change).

To create a generated bookmark for alter ID nlrtlrxv and shove up a corresponding Git branch, we can run a command akin the following:

$ jj git push -c n Creating bookmark push-nlrtlrxvuusk for revision nlrtlrxv Changes to shove to origin:  bookmark: push-nlrtlrxvuusk [add to b1284f61] git: Enumerating objects: 17, done. git: Counting objects: 100% (17/17), done. git: Delta compression using up to 32 threads git: Compressing objects: 100% (14/14), done. git: Writing objects: 100% (16/16), 25.21 KiB | 6.30 MiB/s, done. git: Total 16 (delta 1), reused 5 (delta 0), pack-reused 0 (from 0) remote: Resolving deltas: 100% (1/1), completed alongside 1 local object. remote: remote: Create a drag petition for 'push-nlrtlrxvuusk' on GitHub by visiting: remote: https://github.com/ethanal/example/pull/new/push-nlrtlrxvuusk remote: 

Now jj log shows our alter alongside a correspondingly named bookmark push-nlrtlrxvuusk associated:

$ jj log -r n ○ n [email protected] 2026-11-15 13:33:49 push-nlrtlrxvuusk b │ Use the feature ~ 

We’re liberated to create a PR from this branch on GitHub now. You can customize the bookmark naming scheme alongside the git_push_bookmark template config documented here. It’s a average form to format branch names akin <author name>/<change ID>.

Since jj git shove -c creates a branch name that corresponds to a alter ID, it seems to advance one evolving alter per PR. I think it’s normally finest to lean into these ergonomics, and have one alter per PR.

Updating a branch

To update a branch, the broad procedure is to either squash commits into a alter that is already bookmarked, or create new commits and move the bookmark forward.

Bookmark squash flow

If you choose to squash commits into an existing bookmark (recommended to keep one alter per PR), the stream is as follows.

First, create a new commit on top of our branch.

$ jj new push-nlrtlrxvuusk Working copy (@) now at: s f (empty) (no clarification set) Parent commit (@-) : n b push-nlrtlrxvuuskUse the feature Added 2 files, modified 0 files, removed 0 files 

Then create our edits.

$ jj status Working copy changes: M README.md Working copy (@) : s 6 (no clarification set) Parent commit (@-): n b push-nlrtlrxvuuskUse the feature 

Squash them into the bookmark branch.

$ jj squash --from @ --into push-nlrtlrxvuusk Working copy (@) now at: x 0 (empty) (no clarification set) Parent commit (@-) : n a push-nlrtlrxvuusk*Use the feature 

We now see push-nlrtlrxvuusk has an asterisk next to it, indicating it has changes that haven’t been pushed to the remote. So let’s shove them.

$ jj git push -b push-nlrtlrxvuusk Changes to shove to origin: bookmark: push-nlrtlrxvuusk [move sideways from b1284f61c417 to aeb869aef99b] 

The distant branch now reflects the new changes. The complete output says that we moved the branch sideways from one commit to another commit, which reflects that we did a force-push. jj git shove runs the equal of a git shove --force-with-lease, so if you’re always unclear concerning what a shove procedure would do, you can use the jj git shove --dry-run flag. jj protects you against most hazardous power pushes refusing to rewrite a configurable revset of immutable commits. The default immutable revset is sensible, but you can create it additional or small traditional by configuring your own immutable heads.

Bookmark advancement flow

In this flow, we add new commits on top of our bookmark and afterward move the bookmark to item to our new commit.

Let’s archetypal prepared the new commit.

$ jj new push-nlrtlrxvuusk Working copy (@) now at: p 6 (empty) (no clarification set) Parent commit (@-) : n a push-nlrtlrxvuuskUse the feature 

Then create our edits.

$ jj status Working copy changes: M README.md Working copy (@) : p 8 (no clarification set) Parent commit (@-): n a push-nlrtlrxvuuskUse the feature 
$ jj commit -m "Add a use example" Working copy (@) now at: w 0 (empty) (no clarification set) Parent commit (@-) : p 23 Add a use example 

The bookmark does not automatically move to our new commit. This is the biggest difference between bookmarks and Git branches. For now push-nlrtlrxvuusk motionless points at the commit below:

$ jj log -r n:: @ w [email protected] 2026-11-15 13:51:57 0 │ (empty) (no clarification set) ○ p [email protected] 2026-11-15 13:51:57 23 │ Add a use example ○ n [email protected] 2026-11-15 13:43:16 push-nlrtlrxvuusk a │ Use the feature ~ 

There are multiple ways to move the bookmark to the new commit. The easiest is likely jj bookmark advance, which moves the closest bookmark to the stated commit:

$ jj bookmark advance --to @- Advanced 1 bookmarks to p 23 push-nlrtlrxvuusk*Add a use example 

Now we’re prepared to shove the moved bookmark.

$ jj git push -b push-nlrtlrxvuusk Changes to shove to origin: bookmark: push-nlrtlrxvuusk [move onward from aeb869aef99b to 2341ee4aa554] 

Checking out a distant branch

Since jj is branchless, strictly speaking, we don’t “check out” a branch, but we can create a commit on top of a distant branch. First do the equal of a git fetch, importing distant bookmarks:

$ jj git fetch 

And create a new bare commit on top of the distant branch:

$ jj new some-cool-feature@origin 

Our operating copy now contains all the commits on the distant branch. However, if we were to autumn rear to git, we see that from git’s perspective, we’re in a detached head state, not on any branch.

$ git status Not currently on any branch. nothing to commit, operating tree clean 

This is since jj is editing a commit complete a bookmark, and does not have an equal to git’s “current branch” state.

Pulling in changes from the trunk

Syncing alongside the trunk (e.g. main) is fair a particular example of this flow. We would jj git fetch to update our chief to the upstream main, and afterward rebase our commits on top. For example, the following would rebase my-branch on top of a new main:

jj rebase -b my-branch -o main 

Staying oriented in the graph

jj commit chart manipulation is easiest whenever you have a live commit chart on screen. There are distinct ways you can accomplish this.

jjui is a TUI for jj that allows you to edit the ocular chart directly. I have not personally used this, but I cognize group who akin it.

I favor to have an always-live jj log in the border of my display by way of viddy (a nicer type of observe that supports color):

viddy -t -n1 jj log --ignore-working-copy --color=always 

I propose filtering downward this log to a revset that represents your current work. Here’s a starting point:

visible() & (trunk() | (tracked_remote_bookmarks() & ~::trunk()) | (mutable() & mine())::) 

You power additionally regard trying my experimental project jj-stamp, which is a local code assessment GUI for the squash workflow. Even if you don’t use the squash assessment workflow, it makes a beautiful fine diff spectator alongside a live jj log on the flank and a terminal for operating jj operations.

Stacked PRs, in brief

One of the biggest efficiency gains from jj comes in its capability to assistance stacked PR workflows. This merits its own post, so I’ll keep it short.

Large changes are easier to comprehend whenever they’re damaged up into a sequence of logical steps. Breaking up a ample alter into smaller sequential atoms of assessment makes the entire alter easier to understand. Stacked PRs attempt to leverage this fact to optimize merge throughput, during simultaneously removing pipeline booths in the assessment process.

Let’s say we’re construction a new feature. We can decide we desire to divided up implementation into three stages:

  1. Refactor to create the characteristic easier to implement
  2. Implement the feature
  3. Use the characteristic in another system

jj’s capability to activity on stacked changes alongside automatic rebase is a natural fit for implementing these three stages. Each of the three stages maps to a sole commit, all alongside an connected bookmark/branch/PR:

$ jj log -r oomyzqmz::sxummoow ○ s [email protected] 2026-11-15 14:10:48 ethan/sxummoow b │ Use the feature ○ v [email protected] 2026-11-15 14:06:27 ethan/vqpzktsp f │ Implement the feature ○ o [email protected] 2026-11-15 14:01:19 ethan/oomyzqmz 0 │ Refactor for the feature ~ 

After you execute the archetypal change, you can put up a PR for assessment and immediately commencement operating on the next change. Your activity stream becomes a lengthy queue anywhere you pop off the base as PRs are prepared to merge and shove to the top, alongside no pipeline stalls.

It’s beautiful uncomplicated to manually set up small PR stacks alongside jj and GitHub, but formerly you get hooked on the method (making stacks 5–10 PRs deep), you’ll desire a tool. jj-pancake is my admission into the circle of stacked PR tools. More on that soon.

Resources

  • Official Jujutsu docs. I most frequently mention to the revset spec.
  • Steve Klabnik’s jj tutorial was my archetypal introduction to jj. I don’t think it’s maintained as a durable asset (and I don’t commitment quarry volition be!), but it’s motionless a fine read.
  • I prosecute the jj releases RSS feed. Lately the releases have been packed alongside new features. Overall jj is fairly stable, but the occasional bug is fixed promptly.
  • The Jujutsu discord is energetic and friendly!
  • The blog of East River Source Control, a business that is construction a new forge and code assessment phase intended to assistance Jujutsu well. The creator of Jujutsu, Martin von Zweigbergk, has joined as the CTO, and they have many of another astute group as well. Perhaps a successor to GitHub one day? I’m rooting for them.
  • My individual jj config. You power discover several helpful pseudonyms or tricks here, but I haven’t attempted to create it readable.
  • The jj config of Austin Seipp, a jj maintainer. Cool tricks lie within.
Other Article Hacker News
↑
Close Right Ads
Close Left Ads