zerowidth positive lookahead

An async zsh jujutsu prompt with p10k

2025-08-16T00:00:00-06:00

My zsh configuration uses the powerlevel10k plugin to render the shell prompt. While the p10k project is no longer maintained, it’s still a good choice due to its easy configuration and performance. The git integration uses a system called gitstatus to load git status into the prompt asynchronously, which makes a noticeable difference to responsiveness in large repositories. Unfortunately, because of its tight integration and private APIs, the gitstatus piece of the prompt is difficult to modify or extend for new VCS systems.

I’ve been using the jujutsu VCS in colocated mode. This lets my editor continue to use git status to show file changes. However, since jj leaves git in a “detached HEAD” state, git status prompts are no longer very informative. I’ve figured out a way to add a separate jj-specific prompt segment, including an async version, to show details about the current jj change:

~/jj-prompt pzpu 397c (no description) a-bookmark ⇡1 +1 ±1 -1 ↻1
❯

This prompt shows:

the current working directory
the current change id
the current change’s git SHA
an indicator that there’s no description for the change yet. This shows (empty) when applicable, and also picks up on wip: or todo: in descriptions to show an extra label.
the nearest bookmark a-bookmark and the number of changes (1) between @ and the bookmark.
the number of added, modified, removed, and renamed files as seen by jj.

None of this information is strictly necessary, but the “(empty)” or “(no description)” in particular are helpful. The rest is fun to see, and I figured out how to make it asynchronous to show these the extra details without affecting the prompt’s performance.

Simple synchronous prompt

In p10k.zsh (as generated by the p10k configure command), it’s easy to define your own segments. Let’s start with a simple example showing the current change ID:

prompt_my_jj() {
  local current_workspace change_id display

  command -v jj >/dev/null 2>&1 || return
  current_workspace=$(jj workspace root 2>/dev/null) || return

  change_id=$(jj log --ignore-working-copy \
    --no-graph --limit 1 --color always \
    --revisions @ -T 'change_id.shortest(4)')

  display=$(echo "$change_id" | sed 's/\x1b\[[0-9;]*m/%{&%}/g')
  p10k segment -t "$display"
}

# and add the this jj segment to the powerlevel prompt:
typeset -g POWERLEVEL9K_LEFT_PROMPT_ELEMENTS=(
  # ...
  context                 # user@hostname
  my_jj                   # jj version control status
  # ...
)

Piece by piece, this function:

checks that the current working directory is in a jj workspace
fetches the current change with jj
- --ignore-working-copy prevents jj from taking a new snapshot, it only shows the state of what it currently knows.
- --no-graph disables the visual graph rendering
- --limit 1 ensures we only get the first change in the revisions
- --revisions @ gets only the current change
- --color always forces ANSI colors so we can use jj’s color formatting for the prompt output
- -T 'change_id.shortest(4)' defines a template to fetch the first four characters of the change id.
sed 's/\x1b\[[0-9;]*m/%{&%}/g': jj is emitting colors with ANSI color escape codes, but the prompt doesn’t know to ignore those extra characters for width calculations. The sed regex finds \x1b\[0;] ANSI escapes and wraps them in %{ %}, telling the zsh prompt expansion to treat them as literal escape sequences and thus zero width, so they don’t affect width calculations.
Finally, p10k segment -t "$display" defines the content of the my_jj segment, rendering the current change:

~/jj-prompt spxl
❯

Making it async

We can display basic information quickly, but anything complex will make the prompt unresponsive.

Fortunately, there is a zsh plugin called zsh-async. This plugin lets us define asynchronous jobs, call them, and handle the callback when the job completes. Here’s an example of using this for CI status, and another for docker compose status.

I’m using antigen for zsh plugins, so I’ve added it to my .zshrc. The @main suffix is important: antigen assumes master is the default branch name, which is incorrect for this plugin.

antigen bundle mafredri/zsh-async@main

Initial async setup

First we register global variables. The display string is for the prompt segment, and will be updated asynchronously. The current workspace tracks which workspace we’re in so we can clear the segment if we change to a different workspace. If we didn’t do this, we might temporarily show stale information in the prompt from the previous workspace.

typeset -g _my_jj_display=""
typeset -g _my_jj_workspace=""

Next, we define the worker and callbacks.

# This function is what gets called asynchronously.
# It's given the current workspace as its argument, and outputs the
# formatted prompt segment.
#
# The workspace argument is required, as the async worker can't see
# the global $_my_jj_workspace.
#
# --repository specifies which workspace to operate in.
_my_jj_async() {
  local workspace=$1
  local change_id

  change_id=$(jj log --repository "$workspace" --ignore-working-copy \
    --no-graph --limit 1 --color always \
    --revisions @ -T 'change_id.shortest(3)')

  display=$(echo "$change_id" | sed 's/\x1b\[[0-9;]*m/%{&%}/g')
}

# This callback is called with the result of the async function.
_my_jj_callback() {
  local job_name=$1 exit_code=$2 output=$3 execution_time=$4 stderr=$5 next_pending=$6
  if [[ $exit_code == 0 ]]; then
    _my_jj_display=$output
  else
    _my_jj_display="$output %F{red}$stderr%f"
  fi

  # This is the dynamic piece: once we have the display data, tell p10k to
  # redraw the prompt in-place.
  p10k display -r
}

Then, initialize the plugin and callbacks. We explicitly stop and restart the worker and re-register the callback so we can handle a full reload of the config.

async_init
async_stop_worker _my_jj_worker 2>/dev/null
async_start_worker _my_jj_worker
async_unregister_callback _my_jj_worker 2>/dev/null
async_register_callback _my_jj_worker _my_jj_callback

The prompt itself tracks the current workspace and registers the segment with p10k. The difference from before is that the segment value is in single quotes with a -e flag: this tells p10k to reinterpret the segment each time it’s rendered, allowing the dynamic update to get the latest from $_my_jj_display.

prompt_my_jj() {
  local workspace

  command -v jj >/dev/null 2>&1 || return
  workspace=$(jj workspace root 2>/dev/null) || return

  # track current workspace for the async worker
  if [[ $_my_jj_workspace != "$workspace" ]]; then
    _my_jj_display="" # clear segment if we've moved
    _my_jj_workspace="$workspace"
  fi

  # request async job for the current workspace
  async_job _my_jj_worker _my_jj_async "$workspace"

  # single quotes, we want this to be interpreted each time
  p10k segment -t '$_my_jj_display' -e
}

Fancier prompt

We’ll use some revset aliases and templates defined in jjconfig.toml to make things a little more flexible and easier to update. If you’re looking for template examples, check the built-in configs: jj config list --include-defaults --include-overridden.

First, the revision data should show the current change, the current git SHA, whether or not it’s hidden or conflicted, and (empty) and (no description) when applicable:

[template-aliases]
'format_short_change_id(id)' = 'id.shortest(4)'
'format_short_commit_id(id)' = 'id.shortest(4)'
prompt = '''
separate(" ",
  format_short_change_id_with_hidden_and_divergent_info(self),
  format_short_commit_id(commit_id),
  if(empty, label("empty", "(empty)"), ""),
  if(description == "", label("description placeholder", "(no description)"), ""),
  if(conflict, label("conflict", "(conflict)"), "")
)
'''

Then using this new prompt template:

revision=$(jj log --repository "$workspace" --ignore-working-copy \
  --no-graph --limit 1 --color always \
  --revisions @ -T 'prompt')

We’ll use a revset to find the name and distance to the nearest ancestor bookmark:

[revset-aliases]
'closest_bookmark(to)' = 'heads(::to & bookmarks())'

bookmark=$(jj log --repository "$workspace" --ignore-working-copy \
  --no-graph --limit 1 --color always \
  -r "closest_bookmark(@)" -T 'bookmarks.join(" ")' 2>/dev/null)

distance=$(jj log --repository "$workspace" --ignore-working-copy \
  --no-graph --color never \
  -r "closest_bookmark(@)..@" \
  -T 'change_id ++ "\n"' 2>/dev/null | wc -l | tr -d ' ')

Finally, we can use awk to parse and count file change statuses, and show them with some icons. This uses zsh’s prompt color highlighting syntax to set the colors.

file_status=$(jj log --repository "$workspace" --ignore-working-copy \
  --no-graph --color never --revisions @ \
  -T 'self.diff().files().map(|f| f.status()).join("\n")' 2>/dev/null | \
  sort | uniq -c | awk '
    /modified/ { parts[++i] = "%F{cyan}±" $1 "%f" }
    /added/ { parts[++i] = "%F{green}+" $1 "%f" }
    /removed/ { parts[++i] = "%F{red}-" $1 "%f" }
    /copied/ { parts[++i] = "%F{yellow}⧉" $1 "%f" }
    /renamed/ { parts[++i] = "%F{magenta}↻" $1 "%f" }
    END { for (j=1; j<=i; j++) printf "%s%s", parts[j], (j<i ? " " : "") }
  ')

Tying it all together:

display=$revision

if [[ -n "$bookmark" ]]; then
  display+=" $bookmark"
  if [[ "$distance" -gt 0 ]]; then
    display+=" %7F⇡${distance}"
  fi
fi
if [[ -n "$file_status" ]]; then
  display+=" ${file_status}"
fi

echo "$display" | sed 's/\x1b\[[0-9;]*m/%{&%}/g'

This looks like:

~/jj-prompt pzpu 0441 (no description) main ⇡2 +1 ±1 -1 ↻1
❯

Disabling the `vcs` segment in `jj` workspaces

The prompt examples above left out the vcs segment, which shows a detached HEAD status. If enabled in a colocated jj repository, it looks like this:

~/jj-prompt on @397c199a !3 lvkk aa10 (empty) (no description) main ⇡3
❯              ^^^^^^^^^ ^^
                       |  `- git status shows changed files too
                       `- detached git HEAD SHA

p10k gives us an easy way to selectively disable and enable segments. All it takes is a small addition to the “are we in a jj workspace” check:

if workspace=$(jj workspace root 2>/dev/null); then
  p10k display "*/jj=show"
  p10k display "*/vcs=hide"
else
  p10k display "*/jj=hide"
  p10k display "*/vcs=show"
  return
fi

This can also be accomplished using precmd and chpwd hooks.

Putting it all together

Including custom labels for changes described with “wip”, “todo”, and so forth.

jjconfig.toml:

[template-aliases]
'format_short_change_id(id)' = 'id.shortest(4)'
'format_short_commit_id(id)' = 'id.shortest(4)'
prompt = '''
separate(" ",
  format_short_change_id_with_hidden_and_divergent_info(self),
  format_short_commit_id(commit_id),
  if(empty, label("empty", "(empty)"), ""),
  if(description == "", label("description placeholder", "(no description)"), ""),
  if(description.contains("megamerge"), label("mega", "(mega)"), ""),
  if(description.starts_with("wip"), label("wip", "(wip)"), ""),
  if(description.starts_with("todo"), label("todo", "(todo)"), ""),
  if(description.starts_with("vibe"), label("vibe", "(vibe)"), ""),
  if(description.starts_with("mega"), label("mega", "(mega)"), ""),
  if(conflict, label("conflict", "(conflict)"), "")
)
'''

[revset-aliases]
'closest_bookmark(to)' = 'heads(::to & bookmarks())'

[colors]
wip = "yellow"
todo = "blue"
vibe = "cyan"
mega = "red"

p10k.zsh:

typeset -g _my_jj_display=""
typeset -g _my_jj_workspace=""

prompt_my_jj() {
  local workspace

  command -v jj >/dev/null 2>&1 || return
  if workspace=$(jj workspace root 2>/dev/null); then
    p10k display "*/jj=show"
    p10k display "*/vcs=hide"
  else
    p10k display "*/jj=hide"
    p10k display "*/vcs=show"
    return
  fi

  # track current workspace for the async worker
  if [[ $_my_jj_workspace != "$workspace" ]]; then
    _my_jj_display=""
    _my_jj_workspace="$workspace"
  fi

  # request async job for the current workspace
  async_job _my_jj_worker _my_jj_async "$workspace"

  # note the single quotes, we want this to be interpreted each time
  p10k segment -t '$_my_jj_display' -e
}

# this function is called by the async worker, and does the work
# of calculating the jj status.
_my_jj_async() {
  local workspace=$1
  local display revision bookmark distance

  revision=$(jj log --repository "$workspace" --ignore-working-copy \
    --no-graph --limit 1 --color always \
    --revisions @ -T 'prompt')

  bookmark=$(jj log --repository "$workspace" --ignore-working-copy \
    --no-graph --limit 1 --color always \
    -r "closest_bookmark(@)" -T 'bookmarks.join(" ")' 2>/dev/null)

  distance=$(jj log --repository "$workspace" --ignore-working-copy \
    --no-graph --color never \
    -r "closest_bookmark(@)..@" \
    -T 'change_id ++ "\n"' 2>/dev/null | wc -l | tr -d ' ')

  file_status=$(jj log --repository "$workspace" --ignore-working-copy \
    --no-graph --color never --revisions @ \
    -T 'self.diff().files().map(|f| f.status()).join("\n")' 2>/dev/null | \
    sort | uniq -c | awk '
      /modified/ { parts[++i] = "%F{cyan}±" $1 "%f" }
      /added/ { parts[++i] = "%F{green}+" $1 "%f" }
      /removed/ { parts[++i] = "%F{red}-" $1 "%f" }
      /copied/ { parts[++i] = "%F{yellow}⧉" $1 "%f" }
      /renamed/ { parts[++i] = "%F{magenta}↻" $1 "%f" }
      END { for (j=1; j<=i; j++) printf "%s%s", parts[j], (j<i ? " " : "") }
    ')

  display=$revision

  if [[ -n "$bookmark" ]]; then
    display+=" $bookmark"
    if [[ "$distance" -gt 0 ]]; then
      display+=" %7F⇡${distance}"
    fi
  fi
  if [[ -n "$file_status" ]]; then
    display+=" ${file_status}"
  fi

  echo "$display" | sed 's/\x1b\[[0-9;]*m/%{&%}/g'
}

_my_jj_callback() {
  local job_name=$1 exit_code=$2 output=$3 execution_time=$4 stderr=$5 next_pending=$6
  if [[ $exit_code == 0 ]]; then
    _my_jj_display=$output
  else
    _my_jj_display="$output %F{red}$stderr%f"
  fi
  p10k display -r
}

# finally, initialize and register the worker and callbacks.
# this unregisters first so we can easily reload everything.
async_init
async_stop_worker _my_jj_worker 2>/dev/null
async_start_worker _my_jj_worker
async_unregister_callback _my_jj_worker 2>/dev/null
async_register_callback _my_jj_worker _my_jj_callback

Related work

André Arko also used zsh-async to implement an async jj prompt. I look forward to incorporating some of the different features he’s implemented, including distance from a remote tracked bookmark.

jj tips and tricks

2025-04-26T00:00:00-06:00

Here are some of the tips, tricks, guidelines, and recommendations I’ve learned so far for using Jujutsu well. For more background, see the previous post, what I’ve learned from jj.

I’m using “commit” and “change” interchangeably here. Remember that a jj change is durable and evolves over time, while the underlying commit associated with a change might be different.

Workflows

All new, all the time

Use jj new everywhere unless you really mean to change something in place. And even then, jj new with a jj squash is just as easy, and safer too because you get to decide if and when to squash those changes.

jj automatically abandons empty/undescribed changes, so if you move elsewhere in the repo any temporary jj new change will be cleaned up behind you.

Common workflows

There are two common workflows for making new changes described by the jj community, explained in Steve Klabnik’s tutorial:

Squash workflow
1. describe the work
2. jj new to create a new empty change
3. jj squash to push changes into the described change
Edit workflow
1. Create a new change
2. If the change needs to be split up, create a new change before the current one, then work on that until it’s right, then continue on the main change

Steve also mentions a “one change per PR” style in jj-vcs/jj#2425: Working branches and the JJ “way”

These two workflows are somewhat unfamiliar, but I’m curious to see how they might relate to an in-repo mikado method.

Hunk-wise style

Meanwhile, I’m often using jj like I used git: hack on some code, then decide where to commit the work. I’d make edits, then use git add -p to incrementally stage the relevant subset for a new commit. This pattern works fine with jj commit --interactive, with one exception: the default TUI for interactive staging doesn’t work well for me. I much prefer the hunk-wise yes/no/edit/skip decisionmaking afforded by git add -p. Fortunately, @dubi steinkek in the jj discord implemented this, with a later update from @amiryalsa:

[ui]
diff-editor = "gitpatch"

[merge-tools.gitpatch]
program = "sh"
edit-args = ["-c", '''
  set -eu
  rm -f "$right/JJ-INSTRUCTIONS"
  git -C "$left" init -q
  git -C "$left" add -A
  git -C "$left" commit -q -m baseline --allow-empty
  mv "$left/.git" "$right"
  git -C "$right" add --intent-to-add --ignore-removal .
  git -C "$right" add -p
  git -C "$right" diff-index --quiet --cached HEAD && { echo "No changes done, aborting split."; exit 1; }
  git -C "$right" commit -q -m split
  git -C "$right" reset -q --hard
''',
]

This add -p style also makes jj split --interactive and jj squash --interactive a lot easier. I tried to find a tool that would nicely handle 3-way merges with directories (not single files), and failed. This config gave me a familiar comfortable “handle” for the operations jj allows.

Which one first?

Start by using jj commit, or the equivalent, jj describe && jj new. Once you’re comfortable with the basics, try out squash and split, including their --interactive versions. Don’t be afraid of things like rebase, either, given jj undo’s safety net.

Git interoperability

Colocated mode

I recommend using jj in colocated mode, especially if you’re still dealing with a git upstream. Instead of jj git clone, use git clone && jj git init --colocated, or jj git init --colocated in an existing repository.

Advantages:

This will let you continue to use git commands if needed.
Editors with git integration will still be able to show you inline git annotations or use other features.
It’s easy to try jj without committing fully. You can remove the .jj folder and go back to git any time.

Some downsides or complexities:

git sees your current jj change as a “detached HEAD” state, which makes a shell prompt confusing or useless
You can do git status to see that (as far as git is concerned) there might be untracked changes in your repo. This doesn’t mean that jj hasn’t captured them in the current change, though! You can confirm this with a git diff and a jj status.
The rougher edges of git vs. jj are more visible. You might try going all-in on jj-only instead, as an experiment!

Remember that if anything ever seems out of sync, especially when dealing with branches and bookmarks, you can resync jj and the git repo with jj git import.

For more, see the docs about using jj with GitHub.

Bookmarks and branches

Bookmarks somewhat of a pain to use because they don’t auto-update like git branches. It’s nice that you don’t need named branches to do things with jj, but once a git remote is involved, you need bookmarks, and you have to update them yourself. A common configuration sets up a tug alias to help with this:

[revset-aliases]
'closest_bookmark(to)' = 'heads(::to & bookmarks())'

[aliases]
tug = ["bookmark", "move", "--from", "closest_bookmark(@-)", "--to", "@-"]

Once you’re happy with a series of changes on top of a bookmark, jj tug moves the nearest bookmark up to @-. There are some alternatives in the discussion post that make this more flexible or customizable.

The jj docs about bookmarks talks about how to work with bookmarks in much greater depth.

Immutable branches

GitHub pull requests don’t handle rebases and the resulting force-pushes well: review comments get lost or invalidated, so it’s harder to see what’s changing or what needs to be reviewed. For that reason, you may want to override jj‘s configuration for what is considered an “immutable change” to include any branch that’s been pushed remotely.

[revset-aliases]
# set all remote bookmarks (commits pushed to remote branches) to be immutable
'immutable_heads()' = "builtin_immutable_heads() | remote_bookmarks()"

Note that if you do this, the default log revset will hide every commit but the latest that you’ve pushed for a bookmark. Using a log revset of something like 'default()' = 'coalesce(trunk(), root())::present(@) | ancestors(visible_heads(), 2)' will give you similar results but won’t change what you see when you’ve pushed a bookmark remotely and made those commits immutable.

Miscellaneous

Configs

To see how jj is configured, you can look at:

jj config list --include-defaults --include-overridden
jj/cli/src/config/

While the jj default configuration is fine, I recommend one change in particular:

[git]
push-new-bookmarks = true

This means you don’t need to specify --allow-new when pushing a new bookmark.

The unique prefix for a changeset is highlighted by default, but you can hide the unnecessary bits to make the jj log more concise:

[template-aliases]
'format_short_change_id(id)' = 'id.shortest()'

I figured out how to limit the jj log output to only show recent bookmarks, for long-lived repos with a lot of branches still around:

[ui]
default-command = "log-recent"

[aliases]
log-recent = ["log", "-r", "default() & recent()"]

[revset-aliases]
# the default log revset defined internally:
# 'default()' = 'present(@) | ancestors(immutable_heads().., 2) | present(trunk())'
# or a nicer default:
'default()' = 'coalesce(trunk(),root())::present(@) | ancestors(visible_heads() & recent(), 2)'
'recent()' = 'committer_date(after:"1 month ago")'

Consider tuning the default log output to show what’s most relevant to you: it’s meant to be used for a quick “status” overview.

And a variety of aliases that I’m trying out to reduce typing:

[aliases]
c = ["commit"]
ci = ["commit", "--interactive"]
e = ["edit"]
i = ["git", "init", "--colocate"]
nb = ["bookmark", "create", "-r @-"] # "new bookmark"
pull = ["git", "fetch"]
push = ["git", "push", "--allow-new"]
r = ["rebase"]
s = ["squash"]
si = ["squash", "--interactive"]

Operation log

Remember you have jj op log to see the state of your repo over time. jj undo to go back a step means you can try rebase without concern; jj op restore (not jj restore!) to recover to an earlier state.

Rebases

To understand what rebase can do, jj rebase --help explains well. You can do a lot, not just rebasing the current branch somewhere new.

Working clean

When using git, my working copies were often a mess, leaving a bunch of untracked files around. Most of the time that was intentional, except when I forget to git add a new file I just created too. That’s no longer necessary, but jj captures everything. To continue to ignore a file in your repository after switching to jj, make sure it’s in .gitignore or .git/info/exclude, and then tell jj to forget about the file: jj file untrack <file>.

Replacing `git stash`

Any time you’ve made edits to a new, undescribed change, it’s preserved in the repository history. I suggest that any time you’ve made some changes that you might want to keep (and that you’d have previously stored away with git stash), you at least add a description: jj describe -m "wip for..." so you have some context when you see it in the history later.

Resources and reading

Jujutsu Docs, the official docs
Steve’s Jujutsu Tutorial, the best tutorial
r/rust: Jujutsu VCS tutorial that doesn’t rely on Git, a quick non-git-specific overview of basic jj concepts
jj cheat sheet is an excellent two-pager overview and reference
jj init - What if we could actually replace git? Jujutsu might give us a real shot
A Better Merge Workflow with Jujutsu shows some of the complicated multi-branch and rebase wrangling you can do with jj
Understanding revsets for a better jj log output
jj-vcs/jj#2425: Working branches and the JJ “way”
jj-vcs/jj#5568: Find the closest bookmark in history to advance it forward, describes the tug alias and suggests some other more extensible versions
jj-vcs/jj#5812: How do core Jujutsu developers configure Jujutsu? as an analog to How Core Git Developers Config Git

What’s next?

I haven’t tried any of the GUI/TUI tools yet, such as VisualJJ for VSCode, Jujutsu Kaizen for VSCode, or jj-fzf for the terminal. I’m also planning to look at better integration with the GitHub CLI for creating a bookmark and then opening a pull request related to it in a single command.

Update: my favorite TUI so far is jjui.

I’m not sure yet what a good shell prompt with jj looks like, but I’d like to try some things out, including integration with my p10k zsh prompt.

Updates

2025-05-02 fixed immutable config, it’s builtin_immutable_heads() | remote_bookmarks() not &; added cheat sheet link
2025-06-26
- added missing default() revset alias, including my current preferred version
- added note about how to still display pushed commits when making remote bookmarks immutable
- added --include-overridden to the config list command, it shows more useful context that way
- recommend jjui as a TUI
2025-07-07
- fixed the recent() revset usage in the default() revset alias. I mistakenly only posted the version that doesn’t take an argument. You can use 'recent(revset)' = 'revset & recent()' if you want a version that takes a revset as an argument.
2025-07-26
- updated the hunk-wise gitpatch merge tool based on an improvement from a PR to my dotfiles repo: zerowidth/dotfiles#3. Thanks @amiryalsa!

What I've learned from jj

2025-04-11T00:00:00-06:00

I recently started using the Jujutsu version control system, and it’s changed how I think about working with code. As someone who’s been using git for nearly two decades, it’s refreshing to gain new perspectives on my daily work and get a sense of what might be possible in the future.

Working with git has been great, especially in contrast to what came before. But despite years of development, it still has sharp edges and presents a steep learning curve. Jujutsu doesn’t fix that, exactly, but it sands off some rough edges and makes some different decisions that result in a much safer and far more flexible workflow.

See the next post for jj tips and tricks.

Everything (is) changes

Where git operates solely on commits–snapshots of the codebase explicitly captured with git commit–Jujutsu treats everything as a unique but flexible “change”. Jujutsu unifies several concepts from git: the working copy, commits of the files you’ve edited, the git index, and the stash. While jj still uses git’s snapshot-based storage under the hood, it treats everything as a more generic “change”, each identified with a unique revision. The underlying git commit associated with a change may evolve over time but keeps the same revision identifier.

“Change” is an easily-overloaded term. I’m using “change” here to talk about Jujutsu changes, “commit” for git commits, “edits” or “modifications” for alterations of the codebase, and “revision” to refer to jj‘s identifier for a specific change. Hopefully that’s clear enough, but be aware that documentation and tutorials often use “change” and “commit” interchangeably–it usually doesn’t matter, but I’m keeping those separate here for precision.

A change includes the current state of the files on disk. Any modification to your files, whether editing, moving, renaming, or deleting, is automatically¹ captured by jj. You don’t need to explicitly tell jj about what you’ve done in your working copy, it’s already tracked. This removes the need for an “index” or staging area, since everything is captured already as part of the current change.

A change is associated with one or more parents, just like a git commit. The set of edits it captures may be empty. And, in fact, the default for a new change (jj new) is (empty) (no description): basically a no-op, but tracked as a separate revision from its parent or parents.

Instead of switching branches as you work, you “edit a revision”. When you switch to a different or new change in your repository, that also updates the files on disk to match. This won’t accidentally overwrite anything, because whatever was there would already have been captured in whatever change you were just on. That means switching around to different changes in the repository is safe, and you won’t lose any modifications you’ve made, no matter where you are in the repository’s history.

Instead of just editing an existing change, though, the recommended pattern is to always use jj new : this starts a new, empty change on top of whatever revision you wanted to look at or modify. Because the new change starts out empty, you see the files as they were the parent change, which is what you intended. It’s safer, though: any edits you make will be associated with the new change you’re on, rather than updating the preexisting one. Didn’t want to keep those edits you just made? It’s as easy as jj abandon: the current change goes away and you’re back with a fresh new one. And if you do want to keep them, you can, using jj new to begin a new empty change after the change you were just working on.

This pattern, making a new change on an existing revision that you want to modify also covers the “git stash” pattern naturally. It’s trivial to start a new, different change with jj new: it leaves whatever you were working on right where it was. You can go back to it later if you want, or abandon it if you don’t. These “work in progress” changes have more context than git stash, too: instead of just a stash{3}: WIP on some-branch, they exist in the change history alongside everything else.

While you might think creating new empty changes with jj new all the time would leave your repository history littered with empty changes, jj tries to clean up after itself. If you move away from an empty change to somewhere else–jj new, jj edit, or whatever–it will automatically discard empty changes that you leave behind. Non-empty changes are preserved.

Commits and intentionality

So far I’ve talked about edits and making new changes. What about constructing a commit history, like you’d expect with the normal edit/commit git workflow loop?

A new change has no “description”: it’s like a commit without a commit message. If you’ve made some edits and want to save that work, you can use jj describe to set a description for the current change. Follow it up with a jj new to continue, starting a new change on the one you just described. jj commit is shorthand for this, it’s essentially jj describe && jj new.

A description on a change is optional, but jj won’t let you push un-described commits to a remote repository. Describing a change is a way of saying “I’m done with this change, here’s what’s in it” before moving on.

Along with describing and making new changes, jj squash allows you to take some or all of the current change and “squash” it into another revision. This is usually the immediate parent, but can be any revision. Being able to pick and choose where modifications go makes it easier to be intentional about where something belongs. Say I had a change history q -> r -> s, was working on s, and realized I had something that belongs in q. With jj, it’s as easy as jj squash --into q to push the current changes into q. With git, I’d have to make a fixup commit and then do an interactive rebase to get things into the right place. In practice, I rarely bothered, because of the friction–having to do an interactive rebase at all–and the risk, having to be mindful of what uncommitted changes might be overwritten or lost in my working copy. With jj squash, the current change is pushed into whatever target revision you want. And if that change has children, they’ll all be automatically rebased to incorporate the updated code, no additional work is needed.

It’s also easy to split a change in two with jj split. Should the edits you’ve made belong in separate changes–maybe even for squashing to new places after–it’s now easy to do. It’s also possible with git, but as with other operations, it’s more complicated and difficult.

Rebases with jj are the same as git, conceptually, but both simpler and more direct. If I had s -> t -> u -> v and wanted to reorder them, it’s as easy as jj rebase --revision u --after s, and I’d end up with s -> u -> t -> v, no interactive reordering needed. jj rebase can do far, far more, but the main thing is that it’s easy to do.

These small but important differences from the usual git workflow have meant that I’m more mindful about where any particular code changes “belongs”. It’s easy to put things in the right place, and to build a commit or change series that’s a logical and well-encapsulated series of discrete steps. I’m a lot less likely now to make a series of commits and then throw a few “whoops” and “fix that thing I missed” commits at the end, because I can effortlessly split, squash, update, and rearrange the history.

Flexibility and safety

Along with capturing every edit into a change, jj stores two extra sequences of metadata. The operation log records the state of the repository as it changes, and the evolog (“evolution log”) tracks an individual revision as it changes.

Think of the operation log like the git reflog, which tracks the current HEAD as you commit, switch branches, rebase, and so forth. Going back to the previous state is as easy as jj undo, or jj op restore for an earlier state. Whether what I’ve done is as simple as a jj new or as complex as a multi-headed jj rebase, going back to the prior state is that easy. It’s far more powerful and useful than the git reflog because of how easy it is to restore the entire repository back to a previous state.

The operation log has given me confidence to try all kinds of things. Rebasing revisions to different places, temporarily creating multi-parent merges to do work then unwinding them later once I’ve shipped some PRs, or just experimenting with various commands–it’s all risk-free because I can trivially restore my repository and state back to the way it was. Having the backstop of the operation log means jj rebase is far less scary: if I’m not sure something will work, I can just try it! If it works, great, and if not? jj undo and I can try something else.

As I explained earlier, I recommend using jj new before making edits anywhere. If you forget to do that, any edits you make end up in the current change with whatever was there already. If you didn’t mean to, it would usually be impossible to tease that change back apart to make things “right”, or even to revert back to what the change was before.

Fortunately, the jj evolog, or “evolution log”, tracks the history of a single change over time, like a mini git history just within a single change. Using the evolog, it’s possible to recover the previous version of a change, apply that diff to a new change, and restore the old state: taking what was two separate modifications jammed into one and teasing them apart back into separate changes. Before jj, I would have had to rely on, at best, the undo history in my editor, or would have simply given up on recovering that part of the code history. This feature is perhaps less useful for day to day work, but I was glad to learn it was there and to be able to successfully try it out. For an example of how to do this, see the jj documentation.

Conflict resolution

One of the consequences of being able to modify changes in-place is that all subsequent changes need to be rebased to account for the updated parent. If there were a sequence s -> t -> u -> v and you’d modified t, jj will automatically rebase the rest: s -> t' -> u' -> v'. This includes conflicts, if any arise. The difference from git is that conflicts are not a stop-the-world event! You’ll see in the jj log output that changes have a conflict, but it won’t prevent a command (like an explicit or implicit rebase) from running to completion. You get to choose when and how to resolve the conflicts afterward. I found this a surprising benefit: rebases are already less stressful because of how easy undo is, but now I’m no longer interrupted and forced to resolve conflicts immediately.

The conflict markers take some getting used to. But once you’ve resolved a conflict, any child changes will be automatically rebased again. That often clears the conflict for the rest of the branch.

Interop

Jujutsu doesn’t bother with naming branches for normal operations, nor does it have a “current branch”, but named branches do still exist as “bookmarks”. Like git branches, bookmarks are labels pointing at a change, but unlike git, they don’t move around as you make new changes. Changes in Jujutsu are treated as far more mutable than commits in git, so “move this bookmark to this new change” is a more intentional act. Managing bookmarks is a bit of a hassle still, and has more friction out of the box than I’d prefer. There are some common configs that help, though, which I documented in a followup post.

jj encourages a rebase-friendly workflow, given how easy it is to rebase and rearrange things at any time. This is somewhat incompatible with forges² like GitHub, where force pushes invalidate review comments in pull requests. So there’s somewhat of a mismatch between jj and git models, but it’s not insurmountable. For repositories where I’m collaborating with others, I’m trying a new approach, updating my jj config to consider any commit that’s been pushed to a remote as “immutable”. If I were to try and modify or rebase one of these commits, I’d get an error message. It’s a more restrictive pattern than jj allows for, but I’m going to stick with this for now to reduce confusion in pull requests.

Meanwhile, any change that hasn’t been pushed to a branch yet is fair game! I rebase, split, and squash readily and often.

Using jj in colocated mode, alongside a git repo, means all the git commands still work. jj git init --colocate creates a new .jj directory, and you can now use jj commands. It’s an easy way to experiment with jj without committing fully: try it out, and if it doesn’t feel right or help you like you’d hoped, you can rm -r .jj and go back to git. One interesting note: while jj captures every file in your working copy (i.e. no “dirty” or “untracked” files), git status will still show things the “old” way. If you edit a file, git status will show it as modified but not committed, while jj status will show that it’s modified and that it’s been stored as part of the current change.

Each change is associated with a git commit, or rather, a git commit has a change ID associated with it. When a change is modified, the associated git commit is replaced with a new one with the change’s updated contents. This is irrelevant until you’ve pushed those commits to a remote server. If you edit a change (thereby rewriting the git history), you’ll have to force push to update the remote.

“Units of change” and collaboration

The flexibility afforded by jj is philosophically different from the commit history doesn’t matter approach to git branches. The idea, particularly as realized in the GitHub pull request workflow, is that the real “unit of change” is a pull request, and the individual commits making up a PR are essentially irrelevant.

I’ve been comfortable with that approach for a long time. But now, with the ease at which I can “put the right things in the right place”, I’ve found myself caring more about individual commits: discrete, standalone units of work that don’t necessarily require the broader context of a pull request. I haven’t gone all the way to “one commit per PR” territory, but each commit feels more important to get right because it’s easier to do it that way.

My day-to-day work hasn’t changed much. I’m still using the normal vanilla PR-focused, merge-only GitHub flow. I use jj locally, opening PRs with as clean a history as I can to start. Because of the limitations when force pushes and rebases are involved, I still fall back to “fixup” style commits toward the tail end of a review cycle on a PR.

What’s different is that I can see new paths and possibilities. I’m curious about things like interdiff code review and stacked PRs. I’m eagerly watching developments like per-commit code review in tools like GitButler and efforts to add Change-ID as a supported header in git itself to enable durable change tracking on top of commits. It feels like the pull request as it exists today is fundamentally limited, and I can’t wait to see what’s over the horizon for collaborative tools based on a change-focused iterative model.

Unfortunately, all of the local advantages of jj don’t translate to an upstream repository or collaboration tools. Until there’s more direct integration or a collaboration/code review system that supports jj natively, I’ll have to live with the mismatch in capabilities.

Using jj feels like using git-svn when the rest of the team is still using svn. While I still use git and GitHub for collaboration, I get to use a flexible and fun tool locally. I can try new things with confidence, safe in the knowledge that jj has my back for putting things right if anything goes wrong.

Resources

If you’d like to try jj, I recommend Steve’s Jujutsu Tutorial as the best way to get started. The official docs have all the details including installation instructions.

jj hides or improves upon many of the difficult things about day-to-day work with git, but it still really helps if you’re familiar with how git works. If you’re not, I highly recommend Julia Evans’ How Git Works.

I learned jj as a system building on top of git rather than as a novel standalone utility. This worked well for me because of my experience with git, so I can’t say if it would have an easier learning curve for someone new to version control systems. The underlying git storage abstractions can leak, especially when it comes to working with a remote git repository, so it really helps to know what’s going on.

As a followup to this post, I’ve written down some of the tips and tricks I’ve learned for using jj effectively.

Updates

2025-05-02 hackernews discussion, lobste.rs discussion

Nearly automatically: snapshots are taken when you run a jj command. If you’re in the habit of git status or git diff every now and again, jj status will do the same thing with that extra side effect. ↩
Presumably named after SourceForge, this means any hosting, collaboration, or code review service like GitHub, GitLab, gerritt, etc. ↩

zerowidth positive lookahead

An async zsh jujutsu prompt with p10k

Simple synchronous prompt

Making it async

Initial async setup

Fancier prompt

Disabling the vcs segment in jj workspaces

Putting it all together

Related work

jj tips and tricks

Workflows

All new, all the time

Common workflows

Hunk-wise style

Which one first?

Git interoperability

Colocated mode

Bookmarks and branches

Immutable branches

Miscellaneous

Configs

Operation log

Rebases

Working clean

Replacing git stash

Resources and reading

What’s next?

Updates

What I've learned from jj

Everything (is) changes

Commits and intentionality

Flexibility and safety

Conflict resolution

Interop

“Units of change” and collaboration

Resources

Updates

Disabling the `vcs` segment in `jj` workspaces

Replacing `git stash`