mirror of
https://github.com/martinvonz/jj.git
synced 2024-09-11 05:45:30 +03:00
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 <aseipp@pobox.com> Change-Id: I9f0f78e56157ef434ec239710e00f3bd
This commit is contained in:
parent
9a5c19a3c6
commit
56ba801478
156
README.md
156
README.md
@ -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]
|
||||
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
|
||||
@ -49,14 +131,11 @@ 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.
|
||||
- **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)
|
||||
@ -64,6 +143,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 +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
|
||||
@ -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.
|
||||
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.
|
||||
|
||||
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).
|
||||
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.
|
||||
|
Loading…
Reference in New Issue
Block a user