Repository files navigation

Jujutsu is a powerfulversion control systemfor software projects. You use it to get a copy of your code, track changesto the code, and finally publish those changes for others to see and use.It is designed from the ground up to be easy to use—whether you're new orexperienced, working on brand new projects alone, or large scale softwareprojects with large histories and teams.

Jujutsu is unlike most other systems, because internally it abstracts the userinterface and version control algorithms from thestorage systems used toserve your content. This allows it to serve as a VCS with many possible physicalbackends, that may have their own data or networking models—likeMercurial orBreezy, or hybrid systems like Google's cloud-based design,Piper/CitC.

Today, we use Git repositories as a storage layer to serve and track content,making itcompatible with many of your favorite Git-based tools, right now!All core developers use Jujutsu to develop Jujutsu, right here on GitHub. But itshould hopefully work with your favorite Git forges, too.

We combine many distinct design choices and concepts from other version controlsystems into a single tool. Some of those sources of inspiration include:

• Git: We make an effort tobe fast—with a snappy UX, efficientalgorithms, correct data structures, and good-old-fashioned attention todetail. The default storage backend uses Git repositories for "physicalstorage", for wide interoperability and ease of onboarding.

• Mercurial & Sapling: There are many Mercurial-inspired features, such astherevset language to select commits. There isno explicit indexor staging area. Branches are "anonymous" like Mercurial, so you don't needto make up a name for each small change. Primitives for rewriting history arepowerful and simple. Formatting output is done with a robust template languagethat can be configured by the user.

• Darcs: Jujutsu keeps track of conflicts asfirst-classobjects in its model; they are first-class in the same way commitsare, while alternatives like Git simply think of conflicts as textual diffs.While not as rigorous as systems like Darcs (which is based on a formalizedtheory of patches, as opposed to snapshots), the effect is that many forms ofconflict resolution can be performed and propagated automatically.

And it adds several innovative, useful features of its own:

• Working-copy-as-a-commit: Changes to files arerecorded automaticallyas normal commits, and amended on every subsequent change. This "snapshot"design simplifies the user-facing data model (commits are the only visibleobject), simplifies internal algorithms, and completely subsumes features likeGit's stashes or the index/staging-area.

• Operation log & undo: Jujutsu records every operation that is performed on therepository, from commits, to pulls, to pushes. This makes debugging problems like"what just happened?" or "how did I end up here?" easier,especially whenyou're helping your coworker answer those questions about their repository!And because everything is recorded, you can undo that mistake you just madewith ease. Version control has finally enteredthe 1960s!

• Automatic rebase and conflict resolution: When you modify a commit, everydescendent is automatically rebased on top of the freshly-modified one. Thismakes "patch-based" workflows a breeze. If you resolve a conflict in a commit,theresolution of that conflict is also propagated through descendants aswell. In effect, this is a completely transparent version ofgit rebase --update-refs combined withgit rerere, supported by design.

• Safe, concurrent replication: Have you ever wanted to store your versioncontrolled repositories inside a Dropbox folder? Or continuously backuprepositories to S3? No? Well, now you can!

  The fundamental problem with using filesystems like Dropbox and backup toolslikersync on your typical Git/Mercurial repositories is that they relyonlocal filesystem operations being atomic, serialized, and non-concurrentwith respect to other reads and writes—which isnot true when operating ondistributed file systems, or when operations like concurrent file copies (forbackup) happen while lock files are being held.

  Jujutsu is instead designed to besafe under concurrent scenarios;simply using rsync or Dropbox and then using that resulting repositoryshould never result in a repository in acorrupt state. The worst thatshould happen is that it will expose conflicts between the local and remotestate, leaving you to resolve them.

The command-line tool is calledjj for now because it's easy to type and easyto replace (rare in English). The project is called "Jujutsu" because it matches"jj".

Jujutsu is relatively young, with lots of work to still be done. If you have anyquestions, or want to talk about future plans, please join us on Discord,start aGitHub Discussion, orsend an IRC message to#jujutsu on LiberaChat. The developers monitor all ofthese channels¹.

• December 2024: Thejj Repository has moved to thejj-vcs GitHuborganization.
• November 2024: Version 0.24 is released which addsjj file annotate,which is equivalent togit blame orhg annotate.
• September 2024: Martin gave apresentation about Jujutsu atGit Merge 2024.
• Feb 2024: Version 0.14 is released, which deprecates"jj checkout" and "jj merge",as well asjj init --git, which is now just calledjj git init.
• Oct 2023: Version 0.10.0 is released! Now includes a bundled merge anddiff editor for all platforms, "immutable revsets" to avoid accidentallyedit-ing the wrong revisions, and lots of polish.
• Jan 2023: Martin gave a presentation about Google's plans for Jujutsu atGit Merge 2022!See theslides or therecording.

• Mar 2024: Chris Krycho starteda YouTube series about Jujutsu.
• Feb 2024: Chris Krycho published an article about Jujutsu calledjj initand Steve Klabnik followed up with theJujutsu Tutorial.
• Jan 2024: Jujutsu was featured in an LWN.net article calledJujutsu: a new, Git-compatible version control system.
• Jan 2023: Martin's Talk about Jujutsu at Git Merge 2022,videoand the associatedslides.

The wiki also contains a more extensive list ofmedia references.

Follow theinstallationinstructions toobtain and configurejj.

The best way to get started is probably to go throughthetutorial. Also see theGitcomparison, whichincludes a table ofjj vs.git commands.

As you become more familiar with Jujutsu, the following resources may be helpful:

• TheFAQ.
• TheGlossary.
• Thejj help command (e.g.jj help rebase).
• Thejj help -k <keyword> command (e.g.jj help -k config). Usejj help --helpto see what keywords are available.

If you are using aprerelease version ofjj, you would want to consultthe docs for the prerelease (main branch)version. You can also get therefrom the docs for the latest release by using the website's version switcher. The version switcher is visible inthe header of the website when you scroll to the top of any page.

Jujutsu is designed so that the underlying data and storage model is abstract.Today, only the Git backend is production-ready. The Git backend uses thegitoxide Rust library.

The Git backend is fully featured and maintained, and allows you to use Jujutsuwith any Git remote. The commits you create will look like regular Git commits.You can fetch branches from a regular Git remote and push branches to theremote. You can always switch back to Git.

Here is how you can explore a GitHub repository withjj.

You can even have acolocated localworkspacewhere you can use bothjj andgit commands interchangeably.

Jujutsu uses a real commit to represent the working copy. Checking out a commitresults in a new working-copy commit on top of the target commit. Almost allcommands automatically amend the working-copy commit.

The working-copy being a commit means that commands never fail because theworking copy is dirty (no "error: Your local changes to the followingfiles..."), and there is no need forgit stash. Also, because the working copyis a commit, commands work the same way on the working-copy commit as on anyother commit, so you can set the commit message before you're done with thechanges.

With Jujutsu, the working copy plays a smaller role than with Git. Commandssnapshot the working copy before they start, then they update the repo, and thenthe working copy is updated (if the working-copy commit was modified). Almostall commands (even checkout!) operate on the commits in the repo, leaving thecommon functionality of snapshotting and updating of the working copy tocentralized code. For example,jj restore (similar togit restore) canrestore from any commit and into any commit, andjj describe can set thecommit message of any commit (defaults to the working-copy commit).

All operations you perform in the repo are recorded, along with a snapshot ofthe repo state after the operation. This means that you can easily restore toan earlier repo state, simply undo your operations one-by-one or evenrevert aparticular operation which does not have to be the most recent one.

If an operation results inconflicts,information about those conflicts will be recorded in the commit(s). Theoperation will succeed. You can then resolve the conflicts later. Oneconsequence of this design is that there's no need to continue interruptedoperations. Instead, you get a single workflow for resolving conflicts,regardless of which command caused them. This design also lets Jujutsu rebasemerge commits correctly (unlike both Git and Mercurial).

Basic conflict resolution:

Juggling conflicts:

Whenever you modify a commit, any descendants of the old commit will be rebasedonto the new commit. Thanks to the conflict design described above, that can bedone even if there are conflicts. Bookmarks pointing to rebased commits will beupdated. So will the working copy if it points to a rebased commit.

Besides the usual rebase command, there'sjj describe for editing thedescription (commit message) of an arbitrary commit. There's alsojj diffedit,which lets you edit the changes in a commit without checking it out. To splita commit into two, usejj split. You can even move part of the changes in acommit to any other commit usingjj squash -i --from X --into Y.

The tool is fairly feature-complete, but some important features like supportfor Git submodules are not yet completed. Thereare also several performance bugs. It's likely that workflows and setupsdifferent from what the core developers use are not well supported, e.g. thereis no native support for email-based workflows.

Today, all core developers usejj to work onjj. I (Martin von Zweigbergk)have almost exclusively usedjj to develop the project itself since earlyJanuary 2021. I haven't had to re-clone from source (I don't think I've even hadto restore from backup).

Therewill be changes to workflows and backward-incompatible changes to theon-disk formats before version 1.0.0. For any format changes, we'll try toimplement transparent upgrades (as we've done with recent changes), or provideupgrade commands or scripts if requested.

There are several tools trying to solve similar problems as Jujutsu. Seerelated work for details.

We welcome outside contributions, and there's plenty of things to do, sodon't be shy. Please ask if you want a pointer on something you can help with,and hopefully we can all figure something out.

We do havea few policies andsuggestionsfor contributors. The broad TL;DR:

• Bug reports are very welcome!
• Every commit that lands in themain branch is code reviewed.
• Please behave yourself, and obey the Community Guidelines.
• Thereis a mandatory CLA you must agree to. Importantly, itdoes nottransfer copyright ownership to Google or anyone else; it simply gives us theright to safely redistribute and use your changes.

I (Martin von Zweigbergk,martinvonz@google.com) started Jujutsu as a hobbyproject in late 2019, and it has evolved into my full-time project at Google,with several other Googlers (now) assisting development in various capacities.That said,this is not a Google product.

Jujutsu is available as Open Source Software, under the Apache 2.0 license. SeeLICENSE for details about copyright and redistribution.

Thejj logo was contributed by J. Jennings and is licensed under a CreativeCommons License, seedocs/images/LICENSE.