2021-05-15 19:16:31 +03:00
|
|
|
# Jujutsu
|
2020-12-12 10:37:25 +03:00
|
|
|
|
|
|
|
|
2020-12-12 11:12:04 +03:00
|
|
|
## Disclaimer
|
2020-12-12 10:37:25 +03:00
|
|
|
|
2020-12-12 11:12:04 +03:00
|
|
|
This is not a Google product. It is an experimental version-control system
|
2021-09-08 20:00:47 +03:00
|
|
|
(VCS). It was written by me, Martin von Zweigbergk (martinvonz@google.com). It
|
|
|
|
is my personal hobby project. It does not indicate any commitment or direction
|
|
|
|
from Google.
|
2020-12-12 10:37:25 +03:00
|
|
|
|
|
|
|
|
2020-12-12 11:12:04 +03:00
|
|
|
## Introduction
|
2020-12-12 10:37:25 +03:00
|
|
|
|
2021-10-28 07:45:37 +03:00
|
|
|
Jujutsu is a Git-compatible
|
|
|
|
[DVCS](https://en.wikipedia.org/wiki/Distributed_version_control). It combines
|
2022-01-04 08:31:46 +03:00
|
|
|
features from Git (data model,
|
|
|
|
[speed](https://github.com/martinvonz/jj/discussions/49)), Mercurial (anonymous
|
|
|
|
branching, simple CLI [free from "the index"](docs/git-comparison.md#the-index),
|
2021-12-18 19:07:17 +03:00
|
|
|
[revsets](docs/revsets.md)), and Pijul/Darcs
|
2021-12-12 11:19:39 +03:00
|
|
|
([first-class conflicts](docs/conflicts.md)), with features not found in either
|
|
|
|
of them ([working-copy-as-a-commit](docs/working-copy.md),
|
2021-12-18 17:54:51 +03:00
|
|
|
[undo functionality](docs/operation-log.md), automatic rebase).
|
2020-12-12 10:37:25 +03:00
|
|
|
|
2020-12-12 11:12:04 +03:00
|
|
|
The command-line tool is called `jj` for now because it's easy to type and easy
|
2021-05-15 19:16:31 +03:00
|
|
|
to replace (rare in English). The project is called "Jujutsu" because it matches
|
2021-10-28 07:45:37 +03:00
|
|
|
"jj".
|
2020-12-12 10:37:25 +03:00
|
|
|
|
2021-05-24 00:42:20 +03:00
|
|
|
Features:
|
|
|
|
|
|
|
|
* **Compatible with Git**
|
2021-10-22 19:24:02 +03:00
|
|
|
|
2021-05-24 00:42:20 +03:00
|
|
|
Jujutsu has two backends. One of them is a Git backend (the other is a
|
|
|
|
native one). This lets you use Jujutsu as an alternative interface to Git.
|
|
|
|
The commits you create will look like regular Git commits. You can always
|
|
|
|
switch back to Git.
|
2021-10-22 19:24:02 +03:00
|
|
|
|
2021-10-28 02:56:23 +03:00
|
|
|
<a href="https://asciinema.org/a/DRCzktCyEAxH6j788ZDT6aSjS" target="_blank">
|
|
|
|
<img src="https://asciinema.org/a/DRCzktCyEAxH6j788ZDT6aSjS.svg" />
|
2021-10-22 19:24:02 +03:00
|
|
|
</a>
|
2021-05-24 00:42:20 +03:00
|
|
|
|
|
|
|
* **The working copy is automatically committed**
|
|
|
|
|
|
|
|
Most Jujutsu commands automatically commit the working copy. This leads to a
|
|
|
|
simpler and more powerful interface, since all commands work the same way on
|
|
|
|
the working copy or any other commit. It also means that you can always check
|
|
|
|
out a different commit without first explicitly committing the working copy
|
|
|
|
changes (you can even check out a different commit while resolving merge
|
|
|
|
conflicts).
|
|
|
|
|
2021-10-28 06:38:56 +03:00
|
|
|
<a href="https://asciinema.org/a/zWMv4ffmoXykBtrxvDY6ohEaZ" target="_blank">
|
|
|
|
<img src="https://asciinema.org/a/zWMv4ffmoXykBtrxvDY6ohEaZ.svg" />
|
2021-10-22 23:56:30 +03:00
|
|
|
</a>
|
|
|
|
|
2021-05-24 00:42:20 +03:00
|
|
|
* **Operations update the repo first, then possibly the working copy**
|
|
|
|
|
|
|
|
The working copy is only updated at the end of an operation, after all other
|
|
|
|
changes have already been recorded. This means that you can run any command
|
|
|
|
(such as `jj rebase`) even if the working copy is dirty.
|
|
|
|
|
|
|
|
* **Entire repo is under version control**
|
|
|
|
|
|
|
|
All operations you perform in the repo are recorded, along with a snapshot of
|
|
|
|
the repo state after the operation. This means that you can easily revert to
|
|
|
|
an earlier repo state, or to simply undo a particular operation (which does
|
|
|
|
not necessarily have to be the most recent operation).
|
|
|
|
|
2021-11-08 08:02:32 +03:00
|
|
|
<a href="https://asciinema.org/a/OFOTcm2XlZ09LLEI5bHYM8Alw" target="_blank">
|
|
|
|
<img src="https://asciinema.org/a/OFOTcm2XlZ09LLEI5bHYM8Alw.svg" />
|
2021-10-23 07:59:07 +03:00
|
|
|
</a>
|
|
|
|
|
2021-05-24 00:42:20 +03:00
|
|
|
* **Conflicts can be recorded in commits**
|
|
|
|
|
|
|
|
If an operation results in conflicts, information about those conflicts will
|
|
|
|
be recorded in the commit(s). The operation will succeed. You can then
|
|
|
|
resolve the conflicts later. One consequence of this design is that there's
|
|
|
|
no need to continue interrupted operations. Instead, you get a single
|
|
|
|
workflow for resolving conflicts, regardless of which command caused them.
|
|
|
|
This design also lets Jujutsu rebase merge commits correctly (unlike both Git
|
|
|
|
and Mercurial).
|
|
|
|
|
2021-11-07 03:14:00 +03:00
|
|
|
Basic conflict resolution:
|
2021-11-07 02:08:00 +03:00
|
|
|
<a href="https://asciinema.org/a/MWQz2nAprRXevQEYtaHScN2tJ" target="_blank">
|
|
|
|
<img src="https://asciinema.org/a/MWQz2nAprRXevQEYtaHScN2tJ.svg" />
|
2021-10-23 19:06:40 +03:00
|
|
|
</a>
|
2021-11-07 03:14:00 +03:00
|
|
|
Juggling conflicts:
|
|
|
|
<a href="https://asciinema.org/a/HqYA9SL2tzarPAErpYs684GGR" target="_blank">
|
|
|
|
<img src="https://asciinema.org/a/HqYA9SL2tzarPAErpYs684GGR.svg" />
|
|
|
|
</a>
|
2021-10-23 19:06:40 +03:00
|
|
|
|
2021-10-03 20:17:47 +03:00
|
|
|
* **Automatic rebase**
|
|
|
|
|
|
|
|
Whenever you modify a commit, any descendants of the old commit will be
|
|
|
|
rebased onto the new commit. Thanks to the conflict design described above,
|
|
|
|
that can be done even if there are conflicts. Branches pointing to rebased
|
|
|
|
commits will be updated. So will the working copy if it points to a rebased
|
|
|
|
commit.
|
2021-05-24 00:42:20 +03:00
|
|
|
|
|
|
|
|
2021-09-08 20:00:47 +03:00
|
|
|
## Status ##
|
|
|
|
|
2021-10-28 07:45:37 +03:00
|
|
|
The tool is quite feature-complete, but some important features like (the
|
|
|
|
equivalent of) `git blame` and `git log <paths>` are not yet supported. There
|
|
|
|
are also several performance bugs. It's also likely that workflows and setups
|
|
|
|
different from what I personally use are not well supported. For example,
|
|
|
|
pull-request workflows currently require too many manual steps.
|
|
|
|
|
|
|
|
I have almost exclusively used `jj` to develop the project itself since early
|
|
|
|
January 2021. I haven't had to re-clone from source (I don't think I've even had
|
|
|
|
to restore from backup).
|
|
|
|
|
|
|
|
There *will* be changes to workflows and backward-incompatible changes to the
|
|
|
|
on-disk formats before version 1.0.0. Even the binary's name may change (i.e.
|
|
|
|
away from `jj`). For any format changes, I'll try to implement transparent
|
|
|
|
upgrades (as I've done with recent changes), or provide upgrade commands or
|
|
|
|
scripts if requested.
|
2021-09-08 20:00:47 +03:00
|
|
|
|
|
|
|
|
2021-10-13 18:42:29 +03:00
|
|
|
## Installation
|
|
|
|
|
|
|
|
```shell script
|
|
|
|
# We need the "nightly" Rust toolchain. This command installs that without
|
|
|
|
# changing your default.
|
|
|
|
$ rustup install nightly
|
|
|
|
$ cargo +nightly install --git https://github.com/martinvonz/jj.git
|
|
|
|
```
|
|
|
|
|
2021-10-14 06:38:39 +03:00
|
|
|
To set up command-line completion, source the output of
|
|
|
|
`jj debug completion --bash/--zsh/--fish`. For example, if you use Bash:
|
|
|
|
```shell script
|
|
|
|
$ source <(jj debug completion) # --bash is the default
|
|
|
|
```
|
|
|
|
|
2021-10-14 06:33:17 +03:00
|
|
|
You may also want to configure your name and email so commits are made in your
|
|
|
|
name. Create a `~/.jjconfig` file and make it look something like this:
|
|
|
|
```shell script
|
|
|
|
$ cat ~/.jjconfig
|
|
|
|
[user]
|
|
|
|
name = "Martin von Zweigbergk"
|
|
|
|
email = "martinvonz@google.com"
|
|
|
|
```
|
|
|
|
|
2021-10-13 18:42:29 +03:00
|
|
|
|
2021-09-09 20:56:22 +03:00
|
|
|
## Getting started
|
2021-05-24 00:42:20 +03:00
|
|
|
|
2021-09-09 20:56:22 +03:00
|
|
|
The best way to get started is probably to go through
|
2021-11-19 07:05:43 +03:00
|
|
|
[the tutorial](docs/tutorial.md). Also see the
|
|
|
|
[Git comparison](docs/git-comparison.md), which includes a table of
|
|
|
|
`jj` vs. `git` commands.
|
2021-10-21 01:27:33 +03:00
|
|
|
|
|
|
|
|
|
|
|
## Related work
|
|
|
|
|
|
|
|
There are several tools trying to solve similar problems as Jujutsu. See
|
2021-12-18 18:54:46 +03:00
|
|
|
[related work](docs/related-work.md) for details.
|