AuthonAuthon Blog
tutorial9 min read

Jujutsu vs Git: How to Switch to jj Without Your Team Noticing

jj v0.47.1 runs inside your existing Git checkout, but Git hooks don't run and auto-named push- branches give you away. Here's how to fix both.

AW
Alan West
Authon Team
Jujutsu vs Git: How to Switch to jj Without Your Team Noticing

You can switch from Git to Jujutsu (jj) today without asking anyone, and you don't need a migration plan, an RFC or a Slack thread first. jj keeps its state in a .jj directory next to .git in the checkout you already have, so your teammates, your CI and GitHub keep seeing a plain Git repo. All that changes for you is the command you type.

What gives you away is a handful of defaults, and most of them take a minute to change. I'll cover the setup, a Git-to-jj cheat sheet, pushing PR branches with bookmarks, and the gotchas (hooks, LFS, IDEs, coding agents) that will out you if you skip them. Everything here was checked against jj v0.47.1, the current release (Nov 5).

jj got a lot of attention this week. Ethan Lowman's Jujutsu Primer hit the HN front page with 185 comments, and Bryan O'Sullivan, who kicked off the project at Meta that became Sapling, announced jj-musubi, which live-syncs a jj repo across your machines.

Install jj and run it on your existing Git repo

sh
brew install jj            # or: pacman -S jujutsu
                           # or: cargo install --locked --bin jj jj-cli
jj config set --user user.name "Your Name"
jj config set --user user.email "you@company.com"
cd ~/work/the-repo
jj git init

Set your name and email before jj git init. If you do it afterwards, jj warns that the working-copy commit it already created keeps an empty author, and you have to fix it with jj metaedit --update-author. An empty author on a pushed commit is a quick way to get noticed.

Older guides tell you to run jj git init --colocate. Per the Git compatibility docs, colocation is now the default for jj git init and jj git clone; you opt out with --no-colocate. Every jj command imports from and exports to Git automatically, so git log in another terminal still works.

As soon as you run jj new or jj commit, git status will say "Not currently on any branch". That's expected, because jj has no "current branch". If you need to run a mutating git command, git switch to a branch first.

What actually changes coming from Git

There's no staging area. Every file you touch gets snapshotted into the current change the next time you run any jj command. jj diff shows Git HEAD against your working copy, and the index is ignored.

The working copy is a commit, called @. You don't "make a commit at the end". You describe the one you're in (jj desc -m "...") and start a fresh one on top (jj new); jj commit -m "..." does both. Each change gets a stable change ID like kpqxywon that survives rewrites, while the Git commit hash changes every time.

Everything is undoable. jj undo, jj redo and jj op log cover every operation, including git commands you ran in the same repo, which show up as an "import git refs" operation. In the HN thread, rbehrends wrote that "the single most compelling reason is probably jj undo and jj redo", and I agree.

What Git users don't expect is that a rebase with conflicts doesn't stop. The commit gets marked (conflict), descendants rebase on top of it, and you fix it when you get around to it.

Git to jj command cheat sheet

From the official Git command table, plus the git pull recipe from the GitHub docs:

| You want to | Git | jj |
|---|---|---|
| Status | git status | jj st |
| Stage + commit | git commit -a | jj commit |
| Amend | git commit --amend -a | jj squash |
| Partial amend | git add -p; git commit --amend | jj squash -i |
| Reword parent | git commit --amend --only | jj describe @- |
| New branch off main | git switch -c topic main | jj new main |
| Stash | git stash | jj new @- |
| Throw away work | git reset --hard | jj abandon or jj restore |
| Rebase branch | git rebase B A | jj rebase -b A -o B |
| Interactive reorder | git rebase -i | jj arrange |
| Cherry-pick | git cherry-pick | jj duplicate -o |
| Blame | git blame | jj file annotate |
| Pull | git pull | jj git fetch then jj rebase -o main |
| Continue after conflict | git add f; git rebase --continue | fix the file, jj squash |

There's no jj pull. Also, jj new main doesn't create a branch; that's what bookmarks are for (next section). The current docs use -o (--onto) for the rebase destination, so if a command you copied from an older post fails, check jj rebase --help before blaming jj.

Pushing a GitHub PR branch with jj bookmarks

Bookmarks are jj's version of branches, and they're where Git users get stuck. The primer puts it bluntly: a bookmark doesn't move to your new commit automatically. "This is the biggest difference between bookmarks and Git branches."

The quick path, from the GitHub docs:

sh
jj new main
# ...edit files...
jj commit -m 'feat(bar): add support for bar'
jj git push -c @-
-c (short for --change) creates a bookmark named something like push-mwmpwkwknuzk and pushes it. You push @- because @ is now the empty change you're sitting in.

That branch name is the first thing that gives you away. Nobody on your team names a branch push-mwmpwkwknuzk. HN commenter jon-wood called automatic bookmark naming "100% cursed". So either name it yourself:

sh
jj bookmark create fix-login-timeout -r @-
jj git push --bookmark fix-login-timeout

or make the generated name match your team's convention, in jj config edit --user:

toml
[templates]
git_push_bookmark = '"yourname/push-" ++ change_id.short()'

To address review comments, either add a commit and move the bookmark by hand:

sh
jj new fix-login-timeout
jj commit -m 'address pr comments'
jj bookmark move fix-login-timeout --to @-
jj git push

(the primer uses jj bookmark advance --to @-, which moves the closest bookmark for you), or squash the fix into the original commit and push again. jj makes that a force push automatically. Commits on trunk and tags are immutable by default, so a stray squash can't rewrite main.

jj gotchas that will out you (or bite you)

These come from the compatibility docs or from people in the threads who hit them.

  • Git hooks don't run. jj doesn't support hooks (#405). If your team relies on a pre-commit lint, you'll be the person whose PRs keep failing CI. Run the linter yourself before jj git push.
  • No Git LFS, no submodules. LFS support has been open as #80 since February 2022. Submodules don't show up in the working copy, but they aren't lost either. If your repo uses either one, keep using Git for that repo.
  • .gitattributes is ignored, eol included (#53). On a mixed Windows/Unix team, check that your line endings aren't silently changing.
  • Every new file gets committed: scratch files, .env.local, that 40 MB log. Either tighten .gitignore or turn off auto-tracking with jj config set --user snapshot.auto-track "none()" (nixpulvis's suggestion on HN) and add files explicitly.
  • Your IDE runs git fetch behind your back. The docs warn that this kind of background Git activity can cause conflicted branches and divergent change IDs. If jj log suddenly shows either, don't panic: jj op log, then jj undo.
  • Commits get an extra change-id header. It's harmless, and git commit --amend keeps it, but anyone running git cat-file -p will see it. You can turn it off with git.write-change-id-header.
  • Coding agents still assume Git. On HN, photios said they had to switch back to Git "because of all the agentic tools relying on it" (they've since returned to jj). mhw described Codex getting stuck when a command opened jj's interactive hunk selector or an editor. Colocation helps, since the agent can keep using git against the same checkout, but put a note in your AGENTS.md.

Is jj-musubi worth installing yet?

It's for one person working across several machines (a laptop plus a devbox), not for a team. One machine runs musubi hub, the others exchange history with it over SSH, and every jj snapshot syncs "in moments". It doesn't write to your working copy, so a sync won't change files in the middle of a build. O'Sullivan says plainly that it "has no security model". On Lobsters, pushcx warned that you get divergent commits "prolifically if you're working on a branch in two repos." If you already push throwaway WIP branches just to move code between machines, try it. If you're three days into jj, wait.

Where jj still loses to Git

The staging-area argument on HN went in circles. One camp says the staging area makes you a better programmer. The other points out that jj split and jj squash -i give you the same thing, except the "staging area" is now a commit you can undo. I'm with the second camp.

Where jj actually loses is the boring infrastructure: hooks, LFS, and agents built for Git. Check those before you jj git init. If your repo passes, nobody will know you switched until you start shipping stacked PRs faster than they do.

Have you tried jj and gone back to Git? What was the dealbreaker: hooks, LFS, your IDE, your agent, or bookmarks?

Sources

Jujutsu vs Git: How to Switch to jj Without Your Team Noticing | Authon Blog