From f79816bef1bd6d647740a574aa3431a4e52e04b8 Mon Sep 17 00:00:00 2001 From: Austin Seipp Date: Sun, 29 Oct 2023 11:15:01 -0500 Subject: [PATCH] readme: improved frontmatter, part 2 Summary: What was going to just be some minor touch-ups to the existing content ended in another rework of the frontmatter, this time primarily the sales pitch and basic feature explanation. The motivation here is simple: you should not just encounter a three-word noun that is a hyperlink to pages with 1,000 words actually explaining the three-word noun itself is. It's jarring! Instead, the frontmatter is longer, expanding on each major selling point and similarity to other tools. It actually *describes* the important, distinct design decisions that tell you what the tool is and does, rather than just link you around a bunch. For example, one immediate thing is that calling jj a "DVCS" is actually kind of odd when it later becomes apparent that you can have multiple data model and commit backends; Google for example uses it in a more centralized manner than others would via Piper/CitC. Calling it a "DVCS" is a bit strange in this sense when *really* what we mean is that the Git data model allows independent copies of the repo. Overall I think this is *much* better for people who are just going to see the README and may or may not bounce off immediately. Signed-off-by: Austin Seipp Change-Id: I9f0f78e56157ef434ec239710e00f3bd --- README.md | 111 +++++++++++++++++++++++++++++++++++++++++------------- 1 file changed, 84 insertions(+), 27 deletions(-) diff --git a/README.md b/README.md index 130be094b7..639599105f 100644 --- a/README.md +++ b/README.md @@ -23,21 +23,73 @@ ## Introduction -Jujutsu is a -[Git-compatible](https://martinvonz.github.io/jj/latest/git-compatibility) -[DVCS](https://en.wikipedia.org/wiki/Distributed_version_control). It combines -features from Git (data model, -[speed](https://github.com/martinvonz/jj/discussions/49)), Mercurial (anonymous -branching, simple CLI [free from "the -index"](https://martinvonz.github.io/jj/latest/git-comparison#the-index), -[revsets](https://martinvonz.github.io/jj/latest/revsets), powerful -history-rewriting), and Pijul/Darcs ([first-class -conflicts](https://martinvonz.github.io/jj/latest/conflicts)), with features not -found in most of them -([working-copy-as-a-commit](https://martinvonz.github.io/jj/latest/working-copy), -[undo functionality](https://martinvonz.github.io/jj/latest/operation-log), -automatic rebase, [safe replication via `rsync`, Dropbox, or distributed file -system](https://martinvonz.github.io/jj/latest/technical/concurrency)). +Jujutsu is a powerful [version control system](https://en.wikipedia.org/wiki/Version_control) +system for software projects. You use it to get a copy of the code, track +changes to the code, and finally publish those changes for others to see and +use. Jujutsu is unlike most other systems, because internally it abstracts +the data model used to store your content from its user facing algorithms and +interface. This allows it to serve as a version control interface with many +possible physical backends, such as Git (today), while also open to other +potential backends, like Mercurial, or even more centralized systems like +Perforce. + +Today, by default, we use the Git data model to store and track content, so +it's widely compatible with your favorite Git-based tools. All core Jujutsu +developers use Jujutsu to develop it, right here on GitHub! But it will also +work with your favorite Git forges, too. + +Jujutsu combines many distinct design features from other version control +systems into a single user interface. Those other systems include: + +- **Git**: Like Git, we make an effort to [be fast][perf], from a snappy + UX to efficient algorithms. It also by default shares Git's data model, for + wide interoperability and ease of onboarding. + +- **Mercurial & Sapling**: Many Mercurial inspired features include the [revset] + language to select commits. There is [no explicit index][no-index] or "staging + area". Branches are "anonymous" like Mercurial, so you don't need to make up + a name for each small change. Primitives for rewriting history are powerful + and simple. + +- **Pijul & Darcs**: Jujutsu keeps track of conflicts as [first-class objects][conflicts] + in its model; it tracks them as if it tracked any other file. While not as + rigorous as patch-based systems like Pijul and Darcs, the effect is that many + forms of conflict resolution can be performed and propagated automatically. + +[perf]: https://github.com/martinvonz/jj/discussions/49 +[revset]: https://martinvonz.github.io/jj/latest/revsets/ +[no-index]: https://martinvonz.github.io/jj/latest/git-comparison/#the-index +[conflicts]: https://martinvonz.github.io/jj/latest/conflicts/ + +And it adds several innovative features of its own that those don't have: + +- **Working-copy-as-a-commit**: Changes to files are [recorded automatically][wcc] + as normal commits, and amended on every subsequent change. This "snapshot" + design simplifies the user-facing data model, simplifies internal algorithms, + and completely subsumes features like the Git's stash and index/staging-area. + +- **Operation log, undo**: Jujutsu records every operation that is performed on the + repository, from commits, to pulls, to pushes. This makes debugging problems like + "what just happened?" or "how did I end up here?" easier, *especially* when you're + helping your coworker answer those questions! And because everything is recorded, + you can undo that mistake you just made with ease. Finally: version control + has entered [the 1960s][undo-history]! + +- **Safe, concurrent replication**: Have you ever wanted to store your version + controlled repositories inside a Dropbox folder? No? Well now you can! + Fundamentally the problem with using systems like Dropbox for Git or + Mercurial, or backing them up with `rsync`, is that that they rely on *local + filesystem operations* being atomic, serialized, and non-concurrent with + respect to other writes—which is _not_ true when operating on distributed + file systems or when operations (like copying files to S3) happen while + lock files are being held. Jujutsu is instead designed to be [safe under + concurrent][conc-safety] scenarios; rsync and dropbox will never *corrupt* + your repository. The worst that will happen is that it will expose conflicts + between the local and remote state, leaving you to resolve them. + +[wcc]: https://martinvonz.github.io/jj/latest/working-copy/ +[undo-history]: https://en.wikipedia.org/wiki/Undo#History +[conc-safety]: https://martinvonz.github.io/jj/latest/technical/concurrency/ The command-line tool is called `jj` for now because it's easy to type and easy to replace (rare in English). The project is called "Jujutsu" because it matches @@ -49,12 +101,6 @@ questions, or want to talk about future plans, please join us on Discord or start a [GitHub Discussion](https://github.com/martinvonz/jj/discussions); the developers monitor both channels. -> [!IMPORTANT] -> Jujutsu is an **experimental version control system**. While Git compatibility -> is stable, and most developers use it daily for all their needs, there may -> still be work-in-progress features, suboptimal UX, and workflow gaps that make -> it unusable for your particular use. - ### News and Updates 📣 - **Jan 2023**: Martin gave a presentation about Google's plans for Jujutsu at @@ -64,6 +110,12 @@ developers monitor both channels. ## Getting started +> [!IMPORTANT] +> Jujutsu is an **experimental version control system**. While Git compatibility +> is stable, and most developers use it daily for all their needs, there may +> still be work-in-progress features, suboptimal UX, and workflow gaps that make +> it unusable for your particular use. + Follow the [installation instructions](https://martinvonz.github.io/jj/latest/install-and-setup) to obtain and configure `jj`. @@ -89,17 +141,22 @@ the header of the website when you scroll to the top of any page. ### Compatible with Git -Jujutsu has two -[backends](https://martinvonz.github.io/jj/latest/glossary#backend). One of them -is a Git backend (the other is a native one [^native-backend]). 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. The Git support -uses the [libgit2](https://libgit2.org/) C library. +Jujutsu is designed so that the underlying data and storage model is abstract. +Today, it features two [backends]—one of them uses the Git data model for +storage, while the other is a native one [^native-backend]. + +[backends]: https://martinvonz.github.io/jj/latest/glossary#backend [^native-backend]: At this time, there's practically no reason to use the native backend. The backend exists mainly to make sure that it's possible to eventually add functionality that cannot easily be added to the Git backend. +The Git backend is fully featured and maintained, and allows you to 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. The Git support uses the +[libgit2](https://libgit2.org/) C library. + + You can even have a ["co-located" local