Skip to content

Commit

Permalink
readme: improved frontmatter, part 2
Browse files Browse the repository at this point in the history
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 <[email protected]>
Change-Id: I9f0f78e56157ef434ec239710e00f3bd
  • Loading branch information
thoughtpolice committed Oct 29, 2023
1 parent e5fa591 commit f79816b
Showing 1 changed file with 84 additions and 27 deletions.
111 changes: 84 additions & 27 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
Expand All @@ -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`.
Expand All @@ -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.


<img src="demos/git_compat.png" />

You can even have a ["co-located" local
Expand Down

0 comments on commit f79816b

Please sign in to comment.