1
<div class="title-block" style="text-align: center;" align="center">
2
3
# Jujutsu—a version control system
4
5
<p><img title="jj logo" src="docs/images/jj-logo.svg" width="320" height="320"></p>
6
7
[](https://github.com/jj-vcs/jj/releases)
8
[](https://github.com/jj-vcs/jj/releases)
9
<br/>
10
[](https://github.com/jj-vcs/jj/blob/main/LICENSE)
11
[](https://discord.gg/dkmfj3aGQN)
12
[](https://web.libera.chat/?channel=#jujutsu)
13
14
**[Homepage] • **
15
**[Installation] • **
16
**[Getting Started] • **
17
**[Development Roadmap] • **
18
**[Contributing](#contributing)**
19
20
[Homepage]: https://www.jj-vcs.dev
21
[Installation]: https://docs.jj-vcs.dev/latest/install-and-setup
22
[Getting Started]: https://docs.jj-vcs.dev/latest/tutorial
23
[Development Roadmap]: https://docs.jj-vcs.dev/latest/roadmap
24
25
</div>
26
27
## Introduction
28
29
Jujutsu is a powerful [version control system](https://en.wikipedia.org/wiki/Version_control)
30
for software projects. You use it to get a copy of your code, track changes
31
to the code, and finally publish those changes for others to see and use.
32
It is designed from the ground up to be easy to use—whether you're new or
33
experienced, working on brand new projects alone, or large scale software
34
projects with large histories and teams.
35
36
Jujutsu is unlike most other systems, because internally it abstracts the user
37
interface and version control algorithms from the *storage systems* used to
38
serve your content. This allows it to serve as a VCS with many possible physical
39
backends, that may have their own data or networking models—like [Mercurial] or
40
[Breezy], or hybrid systems like Google's cloud-based design, [Piper/CitC].
41
42
[Mercurial]: https://www.mercurial-scm.org/
43
[Breezy]: https://www.breezy-vcs.org/
44
[Piper/CitC]: https://youtu.be/W71BTkUbdqE?t=645
45
46
Today, we use Git repositories as a storage layer to serve and track content,
47
making it **compatible with many of your favorite Git-based tools, right now!**
48
However, note that only commits and files are stored in Git; bookmarks
49
(branches) and other higher-level metadata are stored in custom storage outside
50
of Git. All core developers use Jujutsu to develop Jujutsu, right here on
51
GitHub. But it should hopefully work with your favorite Git forges, too.
52
53
We combine many distinct design choices and concepts from other version control
54
systems into a single tool. Some of those sources of inspiration include:
55
56
- **Git**: We make an effort to [be fast][perf]—with a snappy UX, efficient
57
algorithms, correct data structures, and good-old-fashioned attention to
58
detail. The default storage backend uses Git repositories for "physical
59
storage", for wide interoperability and ease of onboarding.
60
61
- **Mercurial & Sapling**: There are many Mercurial-inspired features, such as
62
the [revset] language to select commits. There is [no explicit index][no-index]
63
or staging area. Branches are "anonymous" like Mercurial, so you don't need
64
to make up a name for each small change. Primitives for rewriting history are
65
powerful and simple. Formatting output is done with a robust template language
66
that can be configured by the user.
67
68
- **Darcs**: Jujutsu keeps track of conflicts as [first-class
69
objects][conflicts] in its model; they are first-class in the same way commits
70
are, while alternatives like Git simply think of conflicts as textual diffs.
71
While not as rigorous as systems like Darcs (which is based on a formalized
72
theory of patches, as opposed to snapshots), the effect is that many forms of
73
conflict resolution can be performed and propagated automatically.
74
75
[perf]: https://github.com/jj-vcs/jj/discussions/49
76
[revset]: https://docs.jj-vcs.dev/latest/revsets/
77
[no-index]: https://docs.jj-vcs.dev/latest/git-comparison/#the-index
78
[conflicts]: https://docs.jj-vcs.dev/latest/conflicts/
79
80
And it adds several innovative, useful features of its own:
81
82
- **Working-copy-as-a-commit**: Changes to files are [recorded automatically][wcc]
83
as normal commits, and amended on every subsequent change. This "snapshot"
84
design simplifies the user-facing data model (commits are the only visible
85
object), simplifies internal algorithms, and completely subsumes features like
86
Git's stashes or the index/staging-area.
87
88
- **Operation log & undo**: Jujutsu records every operation that is performed on the
89
repository, from commits, to pulls, to pushes. This makes debugging problems like
90
"what just happened?" or "how did I end up here?" easier, *especially* when
91
you're helping your coworker answer those questions about their repository!
92
And because everything is recorded, you can undo that mistake you just made
93
with ease. Version control has finally entered [the 1960s][undo-history]!
94
95
- **Automatic rebase and conflict resolution**: When you modify a commit, every
96
descendent is automatically rebased on top of the freshly-modified one. This
97
makes "patch-based" workflows a breeze. If you resolve a conflict in a commit,
98
the _resolution_ of that conflict is also propagated through descendants as
99
well. In effect, this is a completely transparent version of `git rebase
100
--update-refs` combined with `git rerere`, supported by design.
101
102
> [!WARNING]
103
> The following features are available for use, but experimental; they may have
104
> bugs, backwards incompatible storage changes, and user-interface changes!
105
106
- **Safe, concurrent replication**: Have you ever wanted to store your version
107
controlled repositories inside a Dropbox folder? Or continuously backup
108
repositories to S3? No? Well, now you can!
109
110
The fundamental problem with using filesystems like Dropbox and backup tools
111
like `rsync` on your typical Git/Mercurial repositories is that they rely
112
on *local filesystem operations* being atomic, serialized, and non-concurrent
113
with respect to other reads and writes—which is _not_ true when operating on
114
distributed file systems, or when operations like concurrent file copies (for
115
backup) happen while lock files are being held.
116
117
Jujutsu is instead designed to be [safe under concurrent scenarios][conc-safety];
118
simply using rsync or Dropbox and then using that resulting repository
119
should never result in a repository in a *corrupt state*. The worst that
120
_should_ happen is that it will expose conflicts between the local and remote
121
state, leaving you to resolve them.
122
123
[wcc]: https://docs.jj-vcs.dev/latest/working-copy/
124
[undo-history]: https://en.wikipedia.org/wiki/Undo#History
125
[conc-safety]: https://docs.jj-vcs.dev/latest/technical/concurrency/
126
127
The command-line tool is called `jj` for now because it's easy to type and easy
128
to replace (rare in English). The project is called "Jujutsu" because it matches
129
"jj".
130
131
Jujutsu is relatively young, with lots of work to still be done. If you have any
132
questions, or want to talk about future plans, please join us on Discord
133
[](https://discord.gg/dkmfj3aGQN),
134
start a [GitHub Discussion](https://github.com/jj-vcs/jj/discussions), or
135
send an IRC message to [`#jujutsu` on Libera
136
Chat](https://web.libera.chat/?channel=#jujutsu). The developers monitor all of
137
these channels[^bridge].
138
139
[^bridge]: To be more precise, the `#jujutsu` Libera IRC channel is bridged to
140
one of the channels on jj's Discord. Some of the developers stay on Discord and
141
use the bridge to follow IRC.
142
143
### News and Updates 📣
144
145
- **December 2024**: The `jj` Repository has moved to the `jj-vcs` GitHub
146
organization.
147
- **November 2024**: Version 0.24 is released which adds `jj file annotate`,
148
which is equivalent to `git blame` or `hg annotate`.
149
- **September 2024**: Martin gave a [presentation about Jujutsu][merge-vid-2024] at
150
Git Merge 2024.
151
- **Feb 2024**: Version 0.14 is released, which deprecates ["jj checkout" and "jj merge"](CHANGELOG.md#0140---2024-02-07),
152
as well as `jj init --git`, which is now just called `jj git init`.
153
- **Oct 2023**: Version 0.10.0 is released! Now includes a bundled merge and
154
diff editor for all platforms, "immutable revsets" to avoid accidentally
155
`edit`-ing the wrong revisions, and lots of polish.
156
- **Jan 2023**: Martin gave a presentation about Google's plans for Jujutsu at
157
Git Merge 2022!
158
See the [slides][merge-slides] or the [recording][merge-talk].
159
160
### Related Media
161
162
- **Mar 2024**: Chris Krycho started [a YouTube series about Jujutsu][krycho-yt].
163
- **Feb 2024**: Chris Krycho published an article about Jujutsu called [jj init][krycho]
164
and Steve Klabnik followed up with the [Jujutsu Tutorial][klabnik].
165
- **Jan 2024**: Jujutsu was featured in an LWN.net article called
166
[Jujutsu: a new, Git-compatible version control system][lwn].
167
- **Jan 2023**: Martin's Talk about Jujutsu at Git Merge 2022, [video][merge-talk]
168
and the associated [slides][merge-slides].
169
170
The wiki also contains a more extensive list of [media references][wiki-media].
171
172
[krycho-yt]: https://www.youtube.com/playlist?list=PLelyiwKWHHAq01Pvmpf6x7J0y-yQpmtxp
173
[krycho]: https://v5.chriskrycho.com/essays/jj-init/
174
[klabnik]: https://steveklabnik.github.io/jujutsu-tutorial/
175
[lwn]: https://lwn.net/Articles/958468/
176
[merge-talk]: https://www.youtube.com/watch?v=bx_LGilOuE4
177
[merge-slides]: https://docs.google.com/presentation/d/1F8j9_UOOSGUN9MvHxPZX_L4bQ9NMcYOp1isn17kTC_M/view
178
[merge-vid-2024]: https://www.youtube.com/watch?v=LV0JzI8IcCY
179
[wiki-media]: https://github.com/jj-vcs/jj/wiki/Media
180
181
## Getting started
182
183
> [!IMPORTANT]
184
> Jujutsu is an **experimental version control system**. While Git compatibility
185
> is stable, and most developers use it daily for all their needs, there may
186
> still be work-in-progress features, suboptimal UX, and workflow gaps that make
187
> it unusable for your particular use.
188
189
Follow the [installation
190
instructions](https://docs.jj-vcs.dev/latest/install-and-setup) to
191
obtain and configure `jj`.
192
193
The best way to get started is probably to go through [the
194
tutorial](https://docs.jj-vcs.dev/latest/tutorial). Also see the [Git
195
comparison](https://docs.jj-vcs.dev/latest/git-comparison), which
196
includes a table of `jj` vs. `git` commands.
197
198
As you become more familiar with Jujutsu, the following resources may be helpful:
199
200
- The [FAQ](https://docs.jj-vcs.dev/latest/FAQ).
201
- The [Glossary](https://docs.jj-vcs.dev/latest/glossary).
202
- The `jj help` command (e.g. `jj help rebase`).
203
- The `jj help -k <keyword>` command (e.g. `jj help -k config`). Use `jj help --help`
204
to see what keywords are available.
205
206
If you are using a **prerelease** version of `jj`, you would want to consult
207
[the docs for the prerelease (main branch)
208
version](https://docs.jj-vcs.dev/prerelease/). You can also get there
209
from the docs for the latest release by using the website's version switcher. The version switcher is visible in
210
the header of the website when you scroll to the top of any page.
211
212
## Features
213
214
### Compatible with Git
215
216
Jujutsu is designed so that the underlying data and storage model is abstract.
217
Today, only the Git backend is production-ready. The Git backend uses the
218
[gitoxide](https://github.com/Byron/gitoxide) Rust library.
219
220
[backends]: https://docs.jj-vcs.dev/latest/glossary#backend
221
222
The Git backend is fully featured and maintained, and allows you to use Jujutsu
223
with any Git remote. The commits you create will look like regular Git commits.
224
You can fetch branches from a regular Git remote and push branches to the
225
remote. You can always switch back to Git.
226
227
Here is how you can explore a GitHub repository with `jj`.
228
229
<img src="demos/git_compat.png" />
230
231
You can even have a [colocated local
232
workspace](https://docs.jj-vcs.dev/latest/git-compatibility#colocated-jujutsugit-repos)
233
where you can use both `jj` and `git` commands interchangeably.
234
235
### The working copy is automatically committed
236
237
Jujutsu uses a real commit to represent the working copy. Checking out a commit
238
results in a new working-copy commit on top of the target commit. Almost all
239
commands automatically amend the working-copy commit.
240
241
The working-copy being a commit means that commands never fail because the
242
working copy is dirty (no "error: Your local changes to the following
243
files..."), and there is no need for `git stash`. Also, because the working copy
244
is a commit, commands work the same way on the working-copy commit as on any
245
other commit, so you can set the commit message before you're done with the
246
changes.
247
248
<img src="demos/working_copy.png" />
249
250
### The repo is the source of truth
251
252
With Jujutsu, the working copy plays a smaller role than with Git. Commands
253
snapshot the working copy before they start, then they update the repo, and then
254
the working copy is updated (if the working-copy commit was modified). Almost
255
all commands (even checkout!) operate on the commits in the repo, leaving the
256
common functionality of snapshotting and updating of the working copy to
257
centralized code. For example, `jj restore` (similar to `git restore`) can
258
restore from any commit and into any commit, and `jj describe` can set the
259
commit message of any commit (defaults to the working-copy commit).
260
261
### Entire repo is under version control
262
263
All operations you perform in the repo are recorded, along with a snapshot of
264
the repo state after the operation. This means that you can easily restore to
265
an earlier repo state, simply undo your operations one-by-one or even _revert_ a
266
particular operation which does not have to be the most recent one.
267
268
<img src="demos/operation_log.png" />
269
270
### Conflicts can be recorded in commits
271
272
If an operation results in
273
[conflicts](https://docs.jj-vcs.dev/latest/glossary#conflict),
274
information about those conflicts will be recorded in the commit(s). The
275
operation will succeed. You can then resolve the conflicts later. One
276
consequence of this design is that there's no need to continue interrupted
277
operations. Instead, you get a single workflow for resolving conflicts,
278
regardless of which command caused them. This design also lets Jujutsu rebase
279
merge commits correctly (unlike both Git and Mercurial).
280
281
Basic conflict resolution:
282
283
<img src="demos/resolve_conflicts.png" />
284
285
Juggling conflicts:
286
287
<img src="demos/juggle_conflicts.png" />
288
289
### Automatic rebase
290
291
Whenever you modify a commit, any descendants of the old commit will be rebased
292
onto the new commit. Thanks to the conflict design described above, that can be
293
done even if there are conflicts. Bookmarks pointing to rebased commits will be
294
updated. So will the working copy if it points to a rebased commit.
295
296
### Comprehensive support for rewriting history
297
298
Besides the usual rebase command, there's `jj describe` for editing the
299
description (commit message) of an arbitrary commit. There's also `jj diffedit`,
300
which lets you edit the changes in a commit without checking it out. To split
301
a commit into two, use `jj split`. You can even move part of the changes in a
302
commit to any other commit using `jj squash -i --from X --into Y`.
303
304
## Status
305
306
The tool is fairly feature-complete, but some important features like support
307
for Git submodules are not yet completed. There
308
are also several performance bugs. It's likely that workflows and setups
309
different from what the core developers use are not well supported, e.g. there
310
is no native support for email-based workflows.
311
312
Today, all core developers use `jj` to work on `jj`. I (Martin von Zweigbergk)
313
have almost exclusively used `jj` to develop the project itself since early
314
January 2021. I haven't had to re-clone from source (I don't think I've even had
315
to restore from backup).
316
317
There *will* be changes to workflows and backward-incompatible changes to the
318
on-disk formats before version 1.0.0. For any format changes, we'll try to
319
implement transparent upgrades (as we've done with recent changes), or provide
320
upgrade commands or scripts if requested.
321
322
## Related work
323
324
There are several tools trying to solve similar problems as Jujutsu. See
325
[related work](https://docs.jj-vcs.dev/latest/related-work) for details.
326
327
## Contributing
328
329
We welcome outside contributions, and there's plenty of things to do, so
330
don't be shy. Please ask if you want a pointer on something you can help with,
331
and hopefully we can all figure something out.
332
333
We do have [a few policies and
334
suggestions](https://docs.jj-vcs.dev/prerelease/contributing/)
335
for contributors. The broad TL;DR:
336
337
- Bug reports are very welcome!
338
- Every commit that lands in the `main` branch is code reviewed.
339
- Please behave yourself, and obey the Community Guidelines.
340
- There **is** a mandatory CLA you must agree to. Importantly, it **does not**
341
transfer copyright ownership to Google or anyone else; it simply gives us the
342
right to safely redistribute and use your changes.
343
344
### Mandatory Google Disclaimer
345
346
I (Martin von Zweigbergk, <martinvonz@google.com>) started Jujutsu as a hobby
347
project in late 2019, and it has evolved into my full-time project at Google,
348
with several other Googlers (now) assisting development in various capacities.
349
That said, while Google is one of the main contributors, **this is not a
350
supported Google product**, i.e. support is provided by the community.
351
352
## License
353
354
Jujutsu is available as Open Source Software, under the Apache 2.0 license. See
355
[`LICENSE`](./LICENSE) for details about copyright and redistribution.
356
357
The `jj` logo was contributed by J. Jennings and is licensed under a Creative
358
Commons License, see [`docs/images/LICENSE`](docs/images/LICENSE).
359
