Trying Jujutsu VCS

Jujutsu (jj) is a new version control system that's been picking up a fair amount of interest. While Git has dominated for nearly two decades, Jujutsu promises a simpler, more intuitive approach to version control.

From Skeptic to Cautious Convert

I'll be honest: I was skeptical. A VCS claiming to be "so much easier and more powerful than Git"? Git works fine for most daily workflows, I don't find the command-line all that complex, and the advanced scenarios tend to be rare.

Funny thing, years ago I was equally skeptical of a new VCS when I wrote the post "Don't be a git, just use subversion". In it I argued that Git's complex branching and non-linear nature wasn't worth it for most developers. Here's the Hacker News discussion calling me an idiot.

I'm not a complete luddite. I jumped from CVS to Subversion immediately when it launched.

So, learning from my previous bad take and seeing Jujutsu gaining some traction, I decided to give it a fair shot.

The verdict so far? I don't hate it. In fact, there are some genuinely compelling ideas here.

Getting Started: The Practical Approach

Most Jujutsu tutorials dive straight into advanced features, but let's start with the essentials. Here's how to try it alongside your existing Git projects without disruption.

Installation and Setup

Install Jujutsu:

brew install jj  # macOS
# or your package manager of choice

Initialize in an existing Git repo:

jj git init --colocate

This creates a Jujutsu repository that coexists with your Git repo. You can switch between both tools seamlessly.

The Core Concept: Automatic Staging

Jujutsu flips Git's workflow on its head. Instead of staging changes and then committing, you create a "working space" first, then make changes that are automatically included.

My Daily Workflow

Here's the pattern I've settled into:

1. Create a new working space

jj new

2. Describe what you're working on

jj desc -m "Add user authentication feature"

Note: This can be changed anytime, so don't stress about getting it perfect initially.

3. Make your changes

• Files are automatically staged as you modify them
• Everything respects your .gitignore file
• If something unwanted gets added: jj file untrack [FILE]

4. Start the next change

jj new  # Previous working space becomes a commit

That's it. Your previous working space automatically becomes a commit in both Jujutsu and Git.

Why This Works

This workflow encourages smaller, more focused commits because creating a new working space is so lightweight. No more "fix typo" commits mixed with feature work.

Real Example: Adding This Article

Let me show you exactly how I used Jujutsu to add this article to my blog:

Step 1: Create empty working space

jj new

Step 2: Create article which gets automatically staged:

Step 3: Add description

jj desc -m "Add jujutsu article"

Step 4: Create next working space

jj new

The previous working space is now a proper Git commit (verified with git log):

Note: Pay attention to the Jujutsu change ID which stays the same throughout all the changes above, and the git commit hash which changes with each change until the next working space is created.

After two more changes (adding images and updating the home page), here's what jj log shows:

The real power here is that you can go back and edit any previous commit with jj edit [changeID] or reorder them with jj rebase. But let's keep things simple for now.

Working with Bookmarks (Git Branches)

Jujutsu calls Git branches "bookmarks" – they work similarly but with some key differences that make the distinction worthwhile.

In the log above, you'll see:

• trunk: Your local branch
• trunk@origin: The remote branch

I started with a local commit that hadn't been pushed yet, which is why they're different.

Creating a Feature Branch

To move these commits to a feature branch, create a bookmark pointing to the specific change:

jj bookmark set -r tylvvqpn add/jujutsu

Pushing and Creating Pull Requests

jj git push -b add/jujutsu --allow-new

This pushes your bookmark to GitHub, and you'll get a link to create a PR. If you go to the repo in GitHub you will see the typical new branch PR creation prompt. You can create the PR.

Adding More Commits

To add more commits to your feature branch, use the same workflow:

1. jj new - Create new working space
2. Make changes
3. jj desc -m "Description" - Describe the change

Then repoint your bookmark to include the new change:

jj bookmark set -r @- add/jujutsu

The @- shortcut refers to the change before your current working revision (marked by @).

Now your local bookmark differs from the remote. Update it:

jj git push

When your PR is done and merge on GitHub, sync your local repo:

jj git fetch

Solo Development

If you're working alone without PRs, just use the trunk bookmark:

1. Repoint trunk to your desired revision
2. Push to GitHub
3. Done!

Learning Strategy: Start Simple

These basics will get you productive with Jujutsu. I recommend:

1. Start with the core workflow shown above
2. Gradually add complexity as you encounter new needs
3. Keep lifelines handy: jj undo and jj abandon for when things go wrong
4. Remember it's still Git underneath – you can always fall back to Git commands

The key is experimentation. Try it on a non-critical project first.

What I Actually Like About Jujutsu

Less Mental Overhead

No more git add, git mv, or git rm commands. File operations just work. You focus on your changes, not on Git's staging area.

Lightweight Commit Creation

Starting a new commit with jj new feels effortless. Since descriptions are optional and editable, there's no pressure to get everything perfect upfront.

Flexible Change Management

This is where Jujutsu shines. I can:

• Edit previous commits with jj edit [changeID]
• Split mixed changes with jj split
• Squash related changes together

Real example: While writing this article, I made unrelated site updates. When I forgot to switch contexts, I used jj split to separate the article changes into their own commit, then squashed them with my previous article work.

It Just Works

File moves, deletions, and renames happen automatically. The cognitive load is genuinely lower.

Useful Tips and Configuration

Quick Commit Shortcut

Instead of jj desc + jj new, use:

jj commit -m "Your description"

Increase File Size Limit

Jujutsu's default 1MB file limit is restrictive. Update ~/.config/jj/config.toml:

[snapshot]
max-new-file-size = "10MiB"

Essential Recovery Commands

• jj undo - Undo the last operation
• jj abandon [changeID] - Remove a changeset
• jj log - See your change history
• jj status - Current working space status

Resources

Tutorials and Documentation

• Steve's Jujutsu Tutorial - Excellent beginner-friendly walkthrough
• Official Jujutsu Documentation - Comprehensive reference
• Git Command Table - Side-by-side comparison of Git vs Jujutsu commands

Getting Help

• jj help - Built-in command reference
• jj help [command] - Detailed help for specific commands
• Jujutsu Discussions - Community support

Final Thoughts

Jujutsu isn't revolutionary, but it does solve real friction points in Git workflows. The automatic staging, lightweight commits, and powerful change management make daily version control feel more natural.

Is it worth switching? If Git frustrates you, absolutely try it. If Git works fine for you, Jujutsu might still surprise you with its elegance.

The best part? It coexists with Git, so there's no risk in experimenting. Give it a shot on your next side project.