jj

name: jj description: >- Drives jujutsu (jj) version control on the user's behalf so they don't have to memorize commands. Use for single-agent feature work (the default), whenever the user mentions jujutsu/jj, when undo-safety or a clean rewritable history matters, or when starting/finishing a change in a jj-managed repo. For MULTI-agent parallel work use git worktrees (or jj workspaces) instead — see "jj vs worktrees" below.

jj (jujutsu)

The user adopts the convention: jj for single-agent work, worktrees for multi-agent work. They do NOT want to memorize jj commands — you drive jj correctly on their behalf. Repos are colocated (jj on top of git), so git and gh still work and GitHub/PRs are unchanged.

Preflight (every session in a jj repo)

1. command -v jj — if missing, say so and fall back to plain git. Install: cargo install --locked jj-cli or brew install jj (mention, don't auto-run).
2. Detect a repo: jj root succeeds inside one. If a git repo isn't yet jj-managed and the user wants jj, run jj git init --colocate (keeps .git, adds jj on top; --colocate is the default in recent versions but pass it explicitly).

Mental model (so you operate it correctly)

• The working copy IS a commit, addressed as @. There's no staging area and no "dirty tree" — every edit is auto-committed into @ on the next jj command.
• Changes are anonymous and rewritable. A change keeps a stable change-ID even as you amend it. You freely edit history; jj records each rewrite (undoable).
• Bookmarks ≈ git branches — named pointers you attach to a change to push to GitHub. They do NOT auto-advance with @; you move/set them when ready to push.
• @- means "the parent of the working copy" (i.e. the change you just finished).

The commands you'll actually use

Typical single-agent flow:

jj new main                      # start work
# ...edit files (auto-committed into @)...
jj describe -m "feat: add X"     # give @ a message
# ...keep editing; @ keeps updating...

Pushing to GitHub (colocated repo)

A change needs a bookmark before it can be pushed as a branch:

jj bookmark create my-feature -r @     # name the current change
jj git push --bookmark my-feature      # push (force-pushes safely if rewritten)

Or let jj auto-name and push in one step:

jj git push -c @                       # -c/--change generates a bookmark + pushes

After pushing, open the PR with the existing tooling: gh pr create. To update an existing branch after more edits, move the bookmark then push:

jj bookmark move my-feature --to @
jj git push --bookmark my-feature

The user's gh-bootstrap / branch-hygiene system still applies — squash-merge + delete-on-merge are unchanged because the remote is plain git.

jj vs worktrees (when to use which)

• Single agent, one task at a time → jj. Default. Anonymous changes + jj undo give cheap experimentation and a clean rewritable history.
• Multiple agents in parallel → git worktrees (the user's established habit, managed by their existing worktree/branch-hygiene tooling). Keep using those.
• jj's own equivalent of worktrees is jj workspace — multiple working copies backed by one repo, each with its own @. Use it when staying inside jj for parallel checkouts:

  jj workspace add ../repo-feature-x          # new working copy at that path
  jj workspace add --name fx ../repo-fx        # explicit name
  jj workspace list
  jj workspace forget <name>                   # then rm -rf the dir
  jj workspace update-stale                     # if another workspace moved a shared change
  

  Map of habits: git worktree add → jj workspace add; git worktree remove → jj workspace forget + delete the directory.

Gotchas

• Bookmarks don't follow @. After more commits you must jj bookmark move --to @ before pushing, or the remote branch lags behind.
• No staging area. Don't reach for git add / git commit -p; use jj squash / jj squash -i to shape what goes into a change.
• Don't mix raw git commit with jj in the same repo. Reading via git is fine; let jj own the commits. jj auto-syncs on each command, but manual git commits can surprise it (jj will import them as a new change).
• @ is never empty for long — running almost any jj command snapshots the working copy first, so "uncommitted changes" effectively don't exist.
• update-stale: if a workspace shows a stale working copy, run jj workspace update-stale rather than fighting it.
• Conflicts are first-class — jj records conflicts in a commit instead of blocking. Resolve in the working copy, then jj squash/continue; nothing aborts.
• Version drift: exact flags (rebase -d, --colocate default) vary by jj version. When unsure, jj <cmd> --help is authoritative.