Jujutsu VCS Tutorial

A. Installation

On macOS, install jj via Homebrew:

B. Essential Configuration

Configure your identity for commits. Note that jj uses --user instead of Git's --global:

C. Commit Signing Setup

Many organizations require signed commits for security. Jujutsu supports both GPG and SSH signing - choose whichever you already have configured.

For GPG:

For SSH (simpler option):

Both of these examples use the "own" signing behavior which signs commits you create or edit.

D. Initializing a Co-located Repository

Jujutsu works alongside Git in "co-located" repositories. This means you can use both jj and git commands on the same repo, and they stay synchronized automatically.

After running this command, you'll have both .jj and .git directories. Git will show "detached HEAD" - this is normal and expected with jj. The two systems synchronize on every jj command, so you can use Git tools when needed while primarily working with jj.

A. Understanding the Working Copy

The first mind-shift: in jj, your working copy is a commit. There's no staging area - when you edit files, those changes automatically become part of the current commit (represented by @).

Every time you run a jj command, it automatically snapshots your working directory and amends the @ commit. This eliminates the need for git add - your changes are always part of a commit.

B. Understanding Changes vs Commits

This is a critical distinction: jj tracks both change IDs and commit IDs.

• Change ID: Identifies a logical piece of work. Stays the same when you edit/amend the commit.
• Commit ID: Identifies a specific snapshot. Changes every time you modify the commit.

Why both? Change IDs let you refer to "that feature I'm working on" across rewrites. Commit IDs identify exact historical snapshots. This means you can use change IDs in your daily workflow without worrying about them changing when you amend commits.

Changes eliminate the need for branches in the way that Git imagines them.

C. Basic Operations & Workflow

The key concept: every jj command auto-amends the working copy commit. This means you're always building on your current change until you explicitly create a new one.

Think of jj new as: "I'm done with this change, start a new one"

D. When to Use: jj new vs jj commit vs jj describe

With multiple commands that seem similar, it helps to know when to use each:

jj new: Start a new empty commit on top

• Use when: You want to start fresh work without setting a message yet
• Result: New empty commit becomes @

jj describe: Set/update the commit message for @

• Use when: You want to add/change the message but keep working on @
• Result: @ gets a message, stays as working copy

jj commit -m "message": Shortcut for jj describe + jj new

• Use when: You're done AND have a message ready
• Result: @ gets the message and new empty commit created on top
• Most similar to git commit

jj commit <files>: Like jj split but simpler - move specific files to a new commit

• Use when: You want to commit only certain files
• Result: Selected files go to @, rest stays in new child commit

jj prev / jj next: Navigate linearly through a stack

• Use when: Working through a stack of commits sequentially
• Result: Creates new @ on parent/child (by default) or edits directly (with --edit)
• Shortcut for jj new <parent> or jj new <child>

E. Working with Files

Jujutsu provides commands for inspecting and managing files, though most file operations happen naturally through editing.

Listing and viewing:

Tracking files (usually automatic):

When to use jj file commands:

• jj file list: See what files are in a commit (like git ls-files)
• jj file show: View file contents without checking out
• jj file track/untrack: Rarely needed - use when you want explicit control over tracking

jj interdiff - Compare Two Versions:

One particularly useful command for PR workflows is jj interdiff, which compares what changed between two commits:

When to use:

• Reviewing what changed between PR iterations
• Seeing how a change evolved after feedback
• Note: For same change across history, use jj evolog -p instead

F. Practice: Apply What You've Learned

Now it's your turn! Try these exercises to solidify your understanding:

1. Make some changes to files in your repository
2. Run jj status and jj diff to see what changed
3. Use jj describe -m "Your message" to set a commit message
4. Run jj new to start a new change
5. Make more changes and check jj log to see both commits
6. Try using jj prev to go back to your first change
7. Experiment with jj next to move forward again

Challenge: Create a change with multiple files, then use jj commit <files> to commit only specific files, leaving the rest in a new commit.

A. How jj Makes This Easy

• All operations logged (jj op log)
• jj undo reverses last operation
• Working on your local commits is safe

This means you can confidently rewrite history knowing you can always undo mistakes.

B. Common Operations

Let's understand when and why you'd use these history editing commands:

• squash: Combine multiple commits into one. Use when you have "fix typo" or "address review" commits that should be part of the original change.
• rebase -d <dest>: Move your changes to build on top of a different commit (the "destination"). "Rebasing onto main" means updating your work to start from the latest main branch instead of wherever you originally branched from.
• abandon: Discard a change you no longer need. Unlike delete, this preserves the descendants by rebasing them onto the abandoned commit's parent.

Commands:

jj fix - Automatic Code Formatting:

The jj fix command applies configured formatters (prettier, black, clang-format, etc.) to commits and updates descendants automatically:

Configure tools in .jj/config.toml or global config.

C. Demo Examples

Fixing a typo in an earlier commit:

Here's where jj really shines - you can edit any commit in your history:

When to use squash - combining fixup commits:

If you've accumulated small fixup commits, squash combines them into the original change:

Note: When you edit an earlier commit, jj automatically rebases all descendants. No manual rebasing needed!

Practice: Apply What You've Learned

Try these history editing exercises:

1. Create two commits with jj commit -m "message"
2. Use jj edit to go back to the first commit and make a change
3. Run jj log to see how descendants automatically rebased
4. Create a small "fix typo" commit and use jj squash to combine it with its parent
5. Try jj rebase -d main to move your changes onto a different base
6. Use jj undo if you make a mistake - see how easy it is to recover!

Challenge: Create three commits, then use jj edit to modify the middle one. Watch how jj automatically updates the third commit.

A. What Are Bookmarks?

Bookmarks are jj's version of Git branches - named pointers to commits.

Think of bookmarks as: Labels you attach to commits to track your work and push to GitHub as branches.

B. How Bookmarks Differ from Git Branches

Understanding these differences helps explain why bookmarks feel more natural in daily use:

Key differences:

• Automatic movement: Bookmarks automatically follow commits when you rebase or rewrite them. Git branches stay fixed unless you explicitly move them.
• No "active" bookmark: In Git, you're always "on" a branch. In jj, there's no active bookmark - you work with commits directly via change IDs.
• Conflict handling: Bookmarks can become conflicted (shown with ??) when updated from multiple sources. You resolve these explicitly.

Why this matters: Bookmarks track your intent (which commits belong to which feature) while jj handles the mechanics of keeping them up-to-date.

C. Creating and Managing Bookmarks

D. Understanding Bookmark Tracking

Tracking is a concept that helps keep your local bookmarks synchronized with remotes.

What does tracking do?

When you track a remote bookmark (like feature-x@origin), jj git fetch will automatically create or update a local bookmark (feature-x) to match the remote.

Without tracking: You can still see and reference feature-x@origin, but fetch won't automatically create a local feature-x bookmark.

When to track: Track remote bookmarks you're actively working on and want to stay synchronized with.

E. Which Command to Use?

With multiple bookmark commands available, here's when to use each:

• set: Use this most of the time - works for both new and existing bookmarks
• create: When you want an error if the bookmark already exists (safer but stricter)
• move: When you need advanced features like --allow-backwards or --from filters

F. Tags vs Bookmarks

Tags serve a different purpose than bookmarks - they mark immutable points in history.

Tags are like bookmarks but immutable - they mark specific points (usually releases):

Key difference: Tags don't move when commits are rewritten. Bookmarks follow commits.

Practice: Apply What You've Learned

Practice working with bookmarks:

1. Create a bookmark on your current change: jj bookmark set my-feature -r @
2. Run jj bookmark list to see all your bookmarks
3. Make some changes and use jj log to see the bookmark automatically moved with your commit
4. Try jj bookmark set another-feature -r @- to create a bookmark on your parent commit
5. Use jj bookmark delete to clean up bookmarks you don't need

Challenge: Create two bookmarks pointing to different commits in your history, then use jj edit to work on each one.

A. Fetching Updates

Fetching in jj works similarly to Git, pulling down remote changes:

B. Basic Push (without bookmarks)

For quick prototyping, you can push single changes with auto-generated bookmarks:

This is useful for one-off experiments but for real work you'll want to create explicit bookmarks.

Practice: Apply What You've Learned

Practice syncing with remotes (if you have a remote repository):

1. Run jj git fetch to get the latest changes from your remote
2. Check jj log to see remote bookmarks like main@origin
3. Create a new change and bookmark: jj bookmark set test-sync -r @
4. Try pushing with jj git push --bookmark test-sync --allow-new
5. Make a change to your bookmark and push again (no --allow-new needed this time)
6. Practice rebasing onto the latest main: jj rebase -d main@origin

Challenge: Create a local change, push it, then use jj edit to modify it and push the updated version.

A. Why Stack Changes?

The problem with large PRs:

• Hard to review (reviewers lose focus)
• Risky to merge (many changes at once)
• Slow feedback cycle (must finish everything before getting feedback)

Stacking solves this by:

• Breaking large features into small, reviewable chunks
• Getting feedback on early parts while working on later parts
• Making each PR focused and easy to understand

Example: Instead of one huge "Add user authentication" PR, stack:

1. PR 1: Add database schema for users
2. PR 2: Add authentication API endpoints (builds on PR 1)
3. PR 3: Add login UI (builds on PR 2)

Each PR can be reviewed and merged independently!

What if your change is already too big?

Use jj split to break it apart:

After splitting, you have two commits where you had one - perfect for creating separate PRs!

B. Building Dependent PRs

Here's the workflow for creating a stack:

Note the --allow-new flag - this is required the first time you push a new bookmark to protect against typos.

C. Addressing PR Feedback

When you get feedback on a PR in your stack, jj makes it easy to fix:

All descendant changes automatically rebase on your fixes!

Practice: Apply What You've Learned

Practice creating stacked changes:

1. Start from main: jj new main
2. Make changes for "part 1" of a feature
3. Run jj new to start "part 2" building on part 1
4. Make more changes for part 2
5. Create bookmarks: jj bookmark set feature-part1 -r @- and jj bookmark set feature-part2 -r @
6. Try using jj split on a commit with multiple changes to break it into logical pieces
7. Practice editing an earlier commit in your stack and watch descendants auto-rebase

Challenge: Create a three-commit stack where each commit builds on the previous one. Edit the middle commit and verify the third commit updates automatically.

A. What Are Revsets?

Revsets are jj's query language for selecting commits. Think of them as "commit selectors."

Full reference: https://jj-vcs.github.io/jj/latest/revsets/

You've already been using simple revsets, but they can be much more powerful.

B. Basic Revset Syntax

Symbols:

• @ - your working copy commit
• @- - parent of working copy
• main - a bookmark/branch
• main@origin - bookmark on remote

Common Functions:

• trunk() - main development branches (main, master, trunk)
• tags() - tagged releases
• bookmarks() - all local bookmarks
• remote_bookmarks() - bookmarks on remotes

Examples:

Practice: Apply What You've Learned

Experiment with revsets:

1. Run jj log -r @ to see just your working copy
2. Try jj log -r @- to see your parent commit
3. Use jj log -r main..@ to see all commits between main and your working copy
4. Experiment with jj log -r 'bookmarks()' to see all bookmarked commits
5. Try jj log -r 'trunk()' to see main development branches
6. Use revsets with other commands: jj diff -r @- or jj show -r main

Challenge: Create a revset expression to show all your commits that aren't in main yet.

A. Why This Matters

In Git, it's easy to accidentally rewrite commits that others have based work on, breaking their repositories. Force pushing can overwrite work. These accidents cause frustration and lost time.

Jujutsu prevents these problems through immutable commits - certain commits are protected from rewriting.

B. What Are Immutable Commits?

Jujutsu protects certain commits from being rewritten:

• trunk() - main/master branches
• tags() - tagged releases
• untracked_remote_bookmarks() - commits pushed to remotes

Configuration example (optional to show):

These protections mean:

• No rewriting shared history - can't accidentally rebase commits others have
• No force push needed - jj checks remote state before pushing (like --force-with-lease)
• Safe by default - protects your team from broken histories

C. When You Need to Update a Pushed Commit

If you need to update a commit you've already pushed, jj ensures you do it safely:

Best practice: Don't rewrite commits others have based work on!

Practice: Apply What You've Learned

Understanding immutable commits:

1. Run jj config list | grep immutable to see your immutability settings
2. Try to rebase a commit that's already pushed - observe the safety checks
3. Create a local change, push it, then try jj edit on it
4. Understand which commits are protected: run jj log -r 'trunk()' and jj log -r 'tags()'
5. Practice the safe update pattern: fetch, rebase, then push

Challenge: Intentionally try to force-push to see how jj prevents unsafe operations. Then learn the correct way to update pushed commits.

A. How jj Handles Conflicts Differently

Jujutsu takes a unique approach to conflicts that gives you more flexibility:

Key differences from Git:

• Conflicts are first-class objects: You can commit with unresolved conflicts and continue working
• No special commands needed: No git rebase --continue or git merge --continue - just edit the conflict and the change is automatically amended
• Operations don't fail: jj rebase succeeds even with conflicts; descendants automatically rebase too

Why this matters: You can keep your work rebased on main without blocking on conflict resolution. Resolve conflicts when you're ready.

B. Three Ways to Resolve Conflicts

Method 1: Manual editing (simple conflicts)

Method 2: Using a merge tool (complex conflicts)

Method 3: View what changed during resolution

C. Advanced Features

• Postpone resolution: Keep commits rebased while deferring conflict fixes
• Better conflict markers: Shows "diff to apply" rather than just both sides
• Descendants auto-rebase: When you resolve a conflict, descendants update automatically

D. A Word of Caution

Don't postpone conflicts indefinitely!

While jj lets you defer resolution, conflicts have real consequences:

• Tests may fail: Conflicted code won't compile or run correctly
• Blocks collaboration: Can't share conflicted commits with teammates
• Compounds over time: More rebases = more potential conflicts to untangle
• Breaks local development: Your working copy may be broken until conflicts are resolved

Best practice: Postpone briefly for convenience (finish current thought, switch tasks), but resolve conflicts before:

• Pushing to remote
• Asking for code review
• Switching to work on dependent changes

Practice: Apply What You've Learned

Practice conflict resolution (you'll need two branches that modify the same files):

1. Create a conflict intentionally by rebasing onto a branch with conflicting changes
2. Run jj status to see which files are conflicted
3. Open a conflicted file and examine the conflict markers (<<<<<<<, %%%%%%%, +++++++, >>>>>>>)
4. Try jj resolve --list to see all conflicts
5. Use jj resolve to open your merge tool and resolve a conflict
6. Practice continuing work with unresolved conflicts, then resolve them later
7. Use jj interdiff to review what you changed while resolving

Challenge: Create a stack of three commits, create a conflict in the first one, and watch how jj handles conflicts in descendant commits.

A. jj absorb - Automatic Fixup Distribution

Intelligently moves changes from your working copy into the appropriate commits in your stack:

When to use: After making scattered fixes across a stack of commits - let jj figure out where each change belongs.

B. jj diffedit - Interactive Change Editing

Edit the changes in a commit directly, like using a visual diff editor:

When to use: Surgically edit what a commit changes without touching other commits.

C. jj parallelize - Restructure Commit Relationships

Convert a linear stack into parallel siblings for independent testing:

When to use: You have multiple independent features in a stack that don't actually depend on each other.

D. jj op log and jj op restore - Time Travel

View and restore any previous state of your repository:

When to use: Made a complex mistake? Just restore to before you made it!

E. jj duplicate - Copy Commits

Create copies of commits with the same content but different change IDs:

When to use:

• Experiment with changes without losing the original
• Apply the same change to multiple branches
• Create a backup before risky operations

F. jj bisect - Find When a Bug Was Introduced

Automatically find which commit introduced a bug using binary search:

When to use: When you know something broke but don't know which commit caused it.

Practice: Apply What You've Learned

Experiment with advanced features:

1. Create a stack of commits with scattered changes, then use jj absorb to automatically distribute your working copy changes
2. Try jj duplicate to create a backup of a commit before making risky edits
3. Use jj diffedit to surgically modify what a commit changes
4. Create multiple independent features in a linear stack, then use jj parallelize to make them siblings
5. Practice jj op log to view your command history, then try jj op restore to revert to an earlier state
6. If you have a test suite, experiment with jj bisect run 'your-test-command' to find a breaking commit

Challenge: Create a complex mistake (multiple bad commits), then use jj op log and jj op restore to roll back to before the mistake happened.

Key Takeaways

• Working copy is a commit; jj new to start fresh
• Change IDs stay stable across amendments; commit IDs change
• Immutable commits prevent rewriting shared history
• Operation log (jj op log) + jj undo = safety net
• Colocated repos let you use both jj and git
• Bookmarks track your work; use jj bookmark set for most cases
• Stacking changes creates better PRs

Resources

• jj help [command]
• https://jj-vcs.github.io/jj/latest/