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