Jujutsu (jj) Explained: Git-Compatible VCS Concepts, Installation, Differences from Git, and Migration Decision Points

Jujutsu (jj) is a version control system that uses Git repositories as its storage layer. It maintains compatibility with existing Git tools and workflows while introducing features like automatic working copy commits and the elimination of the index to simplify the development experience. Based on the official documentation, this article organizes the key differences from Git and provides decision points for evaluating a potential switch.

📑Table of Contents

What is Jujutsu (jj) — A Git-Compatible Next-Generation VCS
Installation and Initial Setup
Key Conceptual Differences from Git (Comparison Table)
Basic Commands and Git Command Table
Break-Even Point for Switching
FAQ
Summary

What is Jujutsu (jj) — A Git-Compatible Next-Generation VCS

Jujutsu (jj) is a VCS that leverages Git repositories as its underlying storage layer. Because it uses Git’s object format internally, you can enable jj on an existing Git repository simply by running jj git init --git-repo <path>. This allows you to keep using Git command-line tools and GUIs while adopting jj’s operation model.

The official documentation positions jj as a “next-generation VCS that is Git-compatible.” Its main advantages include automatically committing changes in the working copy and performing operations directly on commits without an index (staging area). This reduces common Git mistakes such as forgetting to git add or git commit.

The ability to use existing Git repositories as-is makes gradual team adoption straightforward. All history and branch information remains in Git format, so you can always revert to using only Git if needed.

Installation and Initial Setup

jj can be installed via Homebrew, cargo, or official binaries. The recommended environment is Rust 1.88 or later and Git 2.41.0 or later. Homebrew users can run brew install jj. For cargo, use cargo install jj.

After installation, set your name and email with jj config set --user user.name "Your Name" and jj config set --user user.email "you@example.com". Enabling shell completion scripts improves usability during command entry.

To try jj on an existing Git repository, run jj git init --git-repo . in the target directory. This creates a .jj directory without modifying the original Git repository.

Key Conceptual Differences from Git (Comparison Table)

The primary differences between jj and Git lie in how the working copy is handled and the overall operation model. The table below summarizes them.

Item	Git	Jujutsu (jj)
Working copy	Manual commit	Automatic commit
Index	Present	None
Branch	Current branch	Bookmark
Conflict	Command fails	Commit possible
Rebase	Manual	Automatic descendant rebase
Operation log	Limited	Enhanced undo functionality

Source: Jujutsu Official Documentation (https://docs.jj-vcs.dev/latest/git-comparison/) (as of June 2026)

Because the working copy is automatically committed, the risk of losing uncommitted changes is reduced. On the other hand, the absence of an index means partial staging is not available. Bookmarks correspond to Git branches but are designed to be lightweight and allow handling multiple bookmarks simultaneously.

When a conflict occurs, jj allows you to commit first and resolve later. This minimizes work interruption. During rebase, descendant commits are automatically rebased, often eliminating the need for manual rebase --onto operations.

Basic Commands and Git Command Table

jj’s main commands correspond to Git equivalents. Details are available in the official Git command table (https://docs.jj-vcs.dev/latest/git-command-table/).

Representative mappings: – jj commit: Corresponds to Git’s commit (commits the entire working copy) – jj rebase: Rebase operation with automatic descendant rebase by default – jj squash: Squashes multiple commits into one – jj bookmark: Manages bookmarks (equivalent to Git’s branch)

After running jj git init on an existing Git repository, you can mix jj and git commands. jj reads and writes the Git repository, so existing Git GUI tools remain usable.

Break-Even Point for Switching

Benefits of migrating to jj include simpler CLI operations, faster rebasing, and improved undo functionality. It is particularly suitable for development styles that involve frequent rebase work on large repositories or require reliable undo.

Drawbacks include a learning curve and the need to verify full compatibility with existing Git tools. Some GUI tools or CI/CD pipelines may not fully support jj-specific concepts such as bookmarks and the operation log.

The break-even point depends on whether you feel friction with daily Git operations. If you spend significant time on index management or conflict resolution in Git, trying jj is worthwhile. Conversely, if your Git workflows are stable and the cost of changing the team’s toolchain is high, it may be better to wait and observe.

FAQ

Q: How do I try jj on a Git repository?

Run jj git init --git-repo . in the target directory. The Git repository remains unchanged, and a .jj directory is added.

Q: How do conflicts get resolved?

You can commit the conflict first and resolve it later with jj resolve or manual editing. Being able to commit means work can continue with minimal interruption.

Q: Can all Git commands still be used?

Most Git commands continue to work in a jj environment, though some are replaced by jj’s own operation model. Check the official table for mappings.

Q: What is the difference between bookmarks and branches?

Bookmarks correspond to Git branches but are lightweight and designed for explicit management of multiple working targets.

Q: Recommended way to read the official documentation

Start with “install-and-setup” and “git-comparison”, then refer to the command table to understand actual operations.

Related articles:

Summary

Jujutsu (jj) is a VCS built on Git that adds automatic working copy management and more efficient rebasing. Based on the official documentation, we have covered installation, key differences from Git, and decision points for switching. The ability to try it while keeping your Git repository intact is a major feature. We recommend starting with jj git init to evaluate how well it fits your daily development workflow.

Source: Jujutsu Official Documentation (https://docs.jj-vcs.dev/latest/)

Author

krona23

Over 20 years in the IT industry, serving as Division Head and CTO at multiple companies running large-scale web services in Japan. Experienced across Windows, iOS, Android, and web development. Currently focused on AI-native transformation. At DevGENT, sharing practical guides on AI code editors, automation tools, and LLMs in three languages.

DevGENT about →

📚 Read Next