version-control

Version Control (Jujutsu)

Note: Current as of jujutsu version 0.37.0. Run jj --version to check your version and jj help for the latest command reference.

Forget everything you know about git.

Use jujutsu exclusively. NEVER use git commands directly — always use jj.

Key Concepts

• @ is the working copy (current change)
• @- is the parent of working copy
• Jujutsu uses bookmarks (not branches)
• Jujutsu uses changes (not commits)
• Working copy is automatically snapshotted (no staging area)
• Changes are immutable; rewriting creates new change IDs

Bookmark Naming Convention

When creating bookmarks (which become branch names when pushed to the git remote), use:

acaloiaro/<task-id>/<generated-bookmark-name>

• acaloiaro — always prefix with the user's identifier.
• <task-id> — the issue/ticket ID only when you're already aware of one in the current context. Use whatever tracker is in play: a Jira key (GREEN-12345), a Trello card ID, a Linear/GitHub issue number, etc. If no task ID is in context, omit this segment entirely and use acaloiaro/<generated-bookmark-name>. Never invent or guess an ID.
• <generated-bookmark-name> — a short, kebab-case summary of the work (e.g., fix-auth-redirect, add-bulk-export).

Interactive Commands

Some jj subcommands require a TTY — they open $EDITOR, a TUI diff selector, or a merge tool. Run these inside a floating multiplexer pane with run-in-mux (works in both zellij and tmux), otherwise they will fail or hang:

run-in-mux -- hookable --interactive --no-exit-code --cmd '<interactive jj command>'

Interactive commands that require run-in-mux:

• jj describe (without -m) — opens $EDITOR for the change description
• jj commit (without -m) — opens $EDITOR for the change description
• jj split — opens the interactive diff selector
• jj split -i / jj split --interactive — interactive diff selector
• jj squash -i / jj squash --interactive — interactive diff selector
• jj restore -i / jj restore --interactive — interactive diff selector
• jj diffedit — opens the configured diff editor
• jj resolve — opens the configured merge tool for conflicts
• jj config edit — opens $EDITOR for the config file
• jj diff --tool difft (and other TUI diff tools) — interactive pager/viewer
• jj log with a TUI pager (less, delta --paging=always, etc.) when output is long

Non-interactive alternative: whenever you already know the description, pass -m "msg" to jj describe/jj commit so no editor is needed and run-in-mux can be skipped.

Common Workflows

Make Changes and Push

# Make your changes to files (automatically snapshotted)
jj describe -m "your commit message"
jj bookmark create acaloiaro/your-bookmark-name
jj git push

Start New Work from Main

jj git fetch
jj new main
# Make changes...
jj describe -m "message"
jj bookmark create acaloiaro/feature-name
jj git push

Update Before Pushing

jj git fetch
jj rebase -d main
jj git push

Address PR Review Comments

jj new your-bookmark
# Make fixes...
jj describe -m "address review comments"
jj bookmark move your-bookmark --to @
jj git push

Squash Fixes into Parent

jj new @-          # Create change on parent
# Make fixes...
jj squash          # Squash into parent

Command Reference

Status & Inspection

jj status              # View working copy status (alias: jj st)
jj log                 # View history
jj log -r '@::'        # View @ and descendants
jj diff                # View changes in @
jj diff -r @-          # View changes in parent
jj show                # Show current change details

Making Changes

jj describe -m "msg"   # Set description for @
jj new                 # Create new empty change on top of @
jj new main            # Create new change on top of main
jj new -m "msg"        # Create new change with description
jj commit -m "msg"     # Describe @ and create new change on top

Bookmark Operations

jj bookmark create name              # Create bookmark at @ (alias: jj b c)
jj bookmark rename OLD NEW           # Rename bookmark (alias: jj b r)
jj bookmark move name --to REV       # Move bookmark to revision (alias: jj b m)
jj bookmark delete name              # Delete bookmark (alias: jj b d)
jj bookmark list                     # List all bookmarks (alias: jj b l)
jj bookmark track name --remote origin  # Track remote bookmark (alias: jj b t)

History Rewriting

jj squash                   # Squash @ into parent
jj squash -r REV            # Squash REV into its parent
jj squash --into REV        # Squash @ into specified revision
jj split                    # Split current change interactively
jj abandon                  # Abandon current change
jj abandon REV              # Abandon specified revision

Rebasing

jj rebase -d main           # Rebase current branch onto main
jj rebase -d main@origin    # Rebase onto remote main
jj rebase -b @ -d main      # Rebase branch containing @ onto main
jj rebase -r @ -d main      # Rebase only @ (not descendants)

Remote Operations

jj git fetch                     # Fetch from all remotes
jj git push                      # Push tracked bookmarks (default)
jj git push --bookmark name      # Push specific bookmark
jj git push --deleted            # Push all deleted bookmarks
jj git push --dry-run            # Preview what will be pushed
jj git remote list               # List remotes

Renaming Bookmarks with Remote:

jj bookmark rename old-name new-name  # Rename locally
jj git push --bookmark new-name       # Push new name
jj git push --deleted                 # Delete old name from remote

Revset Basics

Common revset expressions:

Expression	Description
@	Working copy
@-	Parent of @
@--	Grandparent of @
main	Bookmark named "main"
main@origin	Remote tracking bookmark
x..y	Ancestors of y, not ancestors of x
::x	x and all ancestors
x::	x and all descendants

For complete revset syntax, run jj help -k revsets.

Important Notes

• jj edit is discouraged; prefer jj new + jj squash
• Working copy is always automatically snapshotted
• Use jj help <command> for detailed command help
• Use jj help -k <keyword> for topic help (e.g., jj help -k revsets)