Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

readme: improved front matter, part 2 #2463

Merged
merged 1 commit into from
Nov 5, 2023
Merged

readme: improved front matter, part 2 #2463

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
158 changes: 125 additions & 33 deletions README.md
View file
Open in desktop
thoughtpolice marked this conversation as resolved.
Show resolved Hide resolved
Original file line number Diff line number Diff line change
Expand Up @@ -23,21 +23,103 @@

## 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)
for software projects. You use it to get a copy of your code, track changes
to the code, and finally publish those changes for others to see and use.
It is designed from the ground up to be easy to use—whether you're new or
experienced, working on brand new projects alone, or large scale software
projects with large histories and teams.

Jujutsu is unlike most other systems, because internally it abstracts the user
interface and version control algorithms from the *storage systems* used to
serve your content. This allows it to serve as a VCS with many possible physical
backends, that may have their own data or networking models—like [Mercurial] or
[Breezy], or hybrid systems like Google's cloud-based design, [Piper/CitC].

[Mercurial]: https://www.mercurial-scm.org/
[Breezy]: https://www.breezy-vcs.org/
[Piper/CitC]: https://youtu.be/W71BTkUbdqE?t=645

Today, we use Git repositories as a storage layer to serve and track content,
making it **compatible with many of your favorite Git-based tools, right now!**
All core developers use Jujutsu to develop Jujutsu, right here on GitHub. But it
should hopefully work with your favorite Git forges, too.

We combine many distinct design choices and concepts from other version control
systems into a single tool. Some of those sources of inspiration include:

- **Git**: We make an effort to [be fast][perf]—with a snappy UX, efficient
algorithms, correct data structures, and good-old-fashioned attention to
detail. The default storage backend uses Git repositories for "physical
storage", for wide interoperability and ease of onboarding.

- **Mercurial & Sapling**: There are many Mercurial-inspired features, such as
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. Formatting output is done with a robust template language
that can be configured by the user.

- **Pijul & Darcs**: Jujutsu keeps track of conflicts as [first-class objects][conflicts]
thoughtpolice marked this conversation as resolved.
Show resolved Hide resolved
in its model; they are first-class in the same way commits are, while
alternatives like Git simply think of conflicts as textual diffs. While not
as rigorous as based systems like Darcs and Pijul (which are based on
a formalized theory of patches, as opposed to snapshots), 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, useful features of its own:

- **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 (commits are the only visible
object), simplifies internal algorithms, and completely subsumes features like
Git's stashes or the 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 about their repository!
And because everything is recorded, you can undo that mistake you just made
with ease. Version control has finally entered [the 1960s][undo-history]!

- **Automatic rebase and conflict resolution**: When you modify a commit, every
descendent is automatically rebased on top of the freshly-modified one. This
makes "patch-based" workflows a breeze. If you resolve a conflict in a commit,
the _resolution_ of that conflict is also propagated through descendants as
well. In effect, this is a completely transparent version of `git rebase
--update-refs` combined with `git rerere`, supported by design.

> [!WARNING]
> The following features are available for use, but experimental; they may
> have bugs, backwards incompatible storage changes, and user-interface
> changes!

- **Safe, concurrent replication**: Have you ever wanted to store your version
controlled repositories inside a Dropbox folder? Or continuously backup
repositories to S3? No? Well, now you can!

The fundamental problem with using filesystems like Dropbox and backup tools
like `rsync` on your typical Git/Mercurial repositories is that that they rely
on *local filesystem operations* being atomic, serialized, and non-concurrent
with respect to other reads and writes—which is _not_ true when operating on
distributed file systems, or when operations like concurrent file copies (for
backup) happen while lock files are being held.

Jujutsu is instead designed to be [safe under concurrent scenarios][conc-safety];
simply using rsync or Dropbox and then using that resulting repository
should never result in a repository in a *corrupt state*. The worst that
_should_ 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,21 +131,24 @@ 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 📣

- **Oct 2023**: Version 0.10.0 is released! Now includes a bundled merge and
diff editor for all platforms, "immutable revsets" to avoid accidentally
`edit`-ing the wrong revisions, and lots of polish.
thoughtpolice marked this conversation as resolved.
Show resolved Hide resolved
- **Jan 2023**: Martin gave a presentation about Google's plans for Jujutsu at
Git Merge 2022! See the
[slides](https://docs.google.com/presentation/d/1F8j9_UOOSGUN9MvHxPZX_L4bQ9NMcYOp1isn17kTC_M/view)
or the [recording](https://www.youtube.com/watch?v=bx_LGilOuE4).

## 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 +174,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 a Git repository for storage,
while the other is a native storage backend[^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 Expand Up @@ -179,12 +269,14 @@ commit to any other commit using `jj move`.

The tool is fairly feature-complete, but some important features like (the
equivalent of) `git blame` are not yet supported. There
are also several performance bugs. It's also likely that workflows and setups
different from what the core developers use are not well supported.

I (Martin von Zweigbergk) 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).
are also several performance bugs. It's likely that workflows and setups
different from what the core developers use are not well supported, e.g. there
is no native support for email-based workflows.

Today, all core developers use `jj` to work on `jj`. I (Martin von Zweigbergk)
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.
Expand Down