ok/jj
1
0
Fork 0
forked from mirrors/jj
Code Pull requests Activity

readme: tidy up the front matter a little

Browse source 
Summary: Just a small rework of the very top-level frontmatter. Now:

- Uses `<div>` to center things a little
- Adds top-level links to the new homepage, installation guide, and tutorial
- Reworks the disclaimer and 'Introduction' section. After all, a README should
first say what the project is! I think this reads much better.

Signed-off-by: Austin Seipp <aseipp@pobox.com>
Change-Id: I2d92a21650afec0640add3741d4f20c5
This commit is contained in:
Austin Seipp 2023-09-19 11:20:05 -05:00
parent b9a122ffe7
commit 4acdf72601
1 changed files with 87 additions and 42 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

129
README.md
View file

@ -1,23 +1,23 @@
# Jujutsu VCS <div class="title-block" style="text-align: center;" align="center">
![](https://img.shields.io/github/license/martinvonz/jj) ![](https://img.shields.io/github/v/release/martinvonz/jj) ![](https://img.shields.io/github/release-date/martinvonz/jj) ![](https://img.shields.io/crates/v/jj-cli) # Jujutsu—a version control system
<br/>
![](https://github.com/martinvonz/jj/workflows/build/badge.svg) ![](https://img.shields.io/codefactor/grade/github/martinvonz/jj/main) ![](https://img.shields.io/librariesio/github/martinvonz/jj)
- [Disclaimer](#disclaimer) ![](https://img.shields.io/github/license/martinvonz/jj)
- [Introduction](#introduction) ![](https://img.shields.io/github/v/release/martinvonz/jj)
- [Getting started](#getting-started) ![](https://img.shields.io/github/release-date/martinvonz/jj)
- [Status](#status) ![](https://img.shields.io/crates/v/jj-cli)
- [Related work](#related-work) <br/> ![](https://github.com/martinvonz/jj/workflows/build/badge.svg)
![](https://img.shields.io/codefactor/grade/github/martinvonz/jj/main)
![](https://img.shields.io/librariesio/github/martinvonz/jj)
## Disclaimer **[Homepage] &nbsp;&nbsp;&bull;&nbsp;&nbsp;** **[Installation]
&nbsp;&nbsp;&bull;&nbsp;&nbsp;** **[Getting Started Tutorial]**
This is not a Google product. It is an experimental version-control system [Homepage]: https://martinvonz.github.io/jj
(VCS). I (Martin von Zweigbergk <martinvonz@google.com>) started it as a hobby [Installation]: https://martinvonz.github.io/jj/latest/install-and-setup
project in late 2019. That said, this is now my full-time project at Google. My [Getting Started Tutorial]: https://martinvonz.github.io/jj/latest/tutorial
presentation from Git Merge 2022 has information about Google's plans. See the
[slides](https://docs.google.com/presentation/d/1F8j9_UOOSGUN9MvHxPZX_L4bQ9NMcYOp1isn17kTC_M/view) </div>
or the [recording](https://www.youtube.com/watch?v=bx_LGilOuE4).
## Introduction ## Introduction
@ -26,37 +26,53 @@ Jujutsu is a
[DVCS](https://en.wikipedia.org/wiki/Distributed_version_control). It combines [DVCS](https://en.wikipedia.org/wiki/Distributed_version_control). It combines
features from Git (data model, features from Git (data model,
[speed](https://github.com/martinvonz/jj/discussions/49)), Mercurial (anonymous [speed](https://github.com/martinvonz/jj/discussions/49)), Mercurial (anonymous
branching, simple CLI [free from "the branching, simple CLI
index"](https://martinvonz.github.io/jj/latest/git-comparison#the-index), [free from "the index"](https://martinvonz.github.io/jj/latest/git-comparison#the-index),
[revsets](https://martinvonz.github.io/jj/latest/revsets), powerful [revsets](https://martinvonz.github.io/jj/latest/revsets), powerful
history-rewriting), and Pijul/Darcs ([first-class history-rewriting), and Pijul/Darcs
conflicts](https://martinvonz.github.io/jj/latest/conflicts)), with features not ([first-class conflicts](https://martinvonz.github.io/jj/latest/conflicts)),
found in most of them with features not found in most of them
([working-copy-as-a-commit](https://martinvonz.github.io/jj/latest/working-copy), ([working-copy-as-a-commit](https://martinvonz.github.io/jj/latest/working-copy),
[undo functionality](https://martinvonz.github.io/jj/latest/operation-log), [undo functionality](https://martinvonz.github.io/jj/latest/operation-log),
automatic rebase, [safe replication via `rsync`, Dropbox, or distributed file automatic rebase,
[safe replication via `rsync`, Dropbox, or distributed file
system](https://martinvonz.github.io/jj/latest/technical/concurrency)). system](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 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 to replace (rare in English). The project is called "Jujutsu" because it matches
"jj". "jj".
If you have any questions, please join us on Discord Jujutsu is relatively young, with lots of work to still be done. If you have any
questions, or want to talk about future plans, please join us on Discord
[![Discord](https://img.shields.io/discord/968932220549103686.svg?label=&logo=discord&logoColor=ffffff&color=7389D8&labelColor=6A7EC2)](https://discord.gg/dkmfj3aGQN) [![Discord](https://img.shields.io/discord/968932220549103686.svg?label=&logo=discord&logoColor=ffffff&color=7389D8&labelColor=6A7EC2)](https://discord.gg/dkmfj3aGQN)
or start a [GitHub Discussion](https://github.com/martinvonz/jj/discussions). 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
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 ## Getting started
Follow the [installation Follow the
instructions](https://martinvonz.github.io/jj/latest/install-and-setup) to [installation instructions](https://martinvonz.github.io/jj/latest/install-and-setup)
obtain and configure `jj`. to obtain and configure `jj`.
The best way to get started is probably to go through [the The best way to get started is probably to go through
tutorial](https://martinvonz.github.io/jj/latest/tutorial). Also see the [Git [the tutorial](https://martinvonz.github.io/jj/latest/tutorial). Also see the
comparison](https://martinvonz.github.io/jj/latest/git-comparison), which [Git comparison](https://martinvonz.github.io/jj/latest/git-comparison), which
includes a table of `jj` vs. `git` commands. includes a table of `jj` vs. `git` commands.
As you become more familiar with Jujutsu, the following resources may be helpful: As you become more familiar with Jujutsu, the following resources may be
helpful:
- The [FAQ](https://martinvonz.github.io/jj/latest/FAQ). - The [FAQ](https://martinvonz.github.io/jj/latest/FAQ).
- The [Glossary](https://martinvonz.github.io/jj/latest/glossary). - The [Glossary](https://martinvonz.github.io/jj/latest/glossary).
@ -65,9 +81,9 @@ As you become more familiar with Jujutsu, the following resources may be helpful
If you are using a **prerelease** version of `jj`, you would want to consult If you are using a **prerelease** version of `jj`, you would want to consult
[the docs for the prerelease (main branch) [the docs for the prerelease (main branch)
version](https://martinvonz.github.io/jj/prerelease/). You can also get there version](https://martinvonz.github.io/jj/prerelease/). You can also get there
from the docs for the latest release by using the website's version switcher. The version switcher is visible in from the docs for the latest release by using the website's version switcher.
the header of the website when you scroll to the top of any page. The version switcher is visible in the header of the website when you scroll to
the top of any page.
## Features ## Features
@ -86,8 +102,8 @@ add functionality that cannot easily be added to the Git backend.
<img src="demos/git_compat.png" /> <img src="demos/git_compat.png" />
You can even have a ["co-located" local You can even have a
repository](https://martinvonz.github.io/jj/latest/git-compatibility#co-located-jujutsugit-repos) ["co-located" local repository](https://martinvonz.github.io/jj/latest/git-compatibility#co-located-jujutsugit-repos)
where you can use both `jj` and `git` commands interchangeably. where you can use both `jj` and `git` commands interchangeably.
### The working copy is automatically committed ### The working copy is automatically committed
@ -155,22 +171,22 @@ updated. So will the working copy if it points to a rebased commit.
Besides the usual rebase command, there's `jj describe` for editing the Besides the usual rebase command, there's `jj describe` for editing the
description (commit message) of an arbitrary commit. There's also `jj diffedit`, description (commit message) of an arbitrary commit. There's also `jj diffedit`,
which lets you edit the changes in a commit without checking it out. To split which lets you edit the changes in a commit without checking it out. To split a
a commit into two, use `jj split`. You can even move part of the changes in a commit into two, use `jj split`. You can even move part of the changes in a
commit to any other commit using `jj move`. commit to any other commit using `jj move`.
## Status ## Status
The tool is quite feature-complete, but some important features like (the The tool is quite feature-complete, but some important features like (the
equivalent of) `git blame` are not yet supported. There equivalent of) `git blame` are not yet supported. There are also several
are also several performance bugs. It's also likely that workflows and setups performance bugs. It's also likely that workflows and setups different from what
different from what the core developers use are not well supported. the core developers use are not well supported.
I (Martin von Zweigbergk) have almost exclusively used `jj` to develop the 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 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). (I don't think I've even had to restore from backup).
There *will* be changes to workflows and backward-incompatible changes to the 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. on-disk formats before version 1.0.0. Even the binary's name may change (i.e.
away from `jj`). For any format changes, we'll try to implement transparent away from `jj`). For any format changes, we'll try to implement transparent
upgrades (as we've done with recent changes), or provide upgrade commands or upgrades (as we've done with recent changes), or provide upgrade commands or
@ -180,3 +196,32 @@ scripts if requested.
There are several tools trying to solve similar problems as Jujutsu. See There are several tools trying to solve similar problems as Jujutsu. See
[related work](https://martinvonz.github.io/jj/latest/related-work) for details. [related work](https://martinvonz.github.io/jj/latest/related-work) for details.
## Contributing
We welcome outside contributions, and there's plenty of things to do, so don't
be shy. Please ask if you want a pointer on something you can help with, and
hopefully we can all figure something out.
We do have
[a few policies and suggestions](https://martinvonz.github.io/jj/prerelease/contributing/)
for contributors. The broad TL;DR:
- Bug reports are very welcome!
- Every single commit that lands in `main` goes through code review.
- Please behave yourself, and obey the Community Guidelines.
- There **is** a mandatory CLA you must agree to. Importantly, it **does not**
transfer copyright ownership to Google or anyone else; it simply gives us the
right to safely redistribute and use your changes.
### Mandatory Google Disclaimer
I (Martin von Zweigbergk, <martinvonz@google.com>) started Jujutsu as a hobby
project in late 2019, and it has evolved into my full-time project at Google,
with several other Googlers (now) assisting development in various capacities.
That said, **this is not a Google product**.
## License
Jujutsu is available as Open Source Software, under the Apache 2.0 license. See
[LICENSE](./LICENSE) for details about copyright and redistribution.