diff --git a/README.md b/README.md index f903a0b1b0..01a3e54300 100644 --- a/README.md +++ b/README.md @@ -21,17 +21,21 @@ or the [recording](https://www.youtube.com/watch?v=bx_LGilOuE4). ## Introduction -Jujutsu is a [Git-compatible](docs/git-compatibility.md) +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"](docs/git-comparison.md#the-index), -[revsets](docs/revsets.md), powerful history-rewriting), and Pijul/Darcs -([first-class conflicts](docs/conflicts.md)), with features not found in most -of them ([working-copy-as-a-commit](docs/working-copy.md), -[undo functionality](docs/operation-log.md), automatic rebase, -[safe replication via `rsync`, Dropbox, or distributed file -system](docs/technical/concurrency.md)). +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)). 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 @@ -40,30 +44,41 @@ to replace (rare in English). The project is called "Jujutsu" because it matches If you have any questions, 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) or start a [GitHub Discussion](https://github.com/martinvonz/jj/discussions). -The [glossary](docs/glossary.md) may also be helpful. - ## Getting started -Follow the [installation instructions](docs/install-and-setup.md) to obtain and configure `jj`. +Follow the [installation +instructions](https://martinvonz.github.io/jj/latest/install-and-setup) to +obtain and configure `jj`. + +The best way to get started is probably to go through [the +tutorial](https://martinvonz.github.io/jj/latest/tutorial). Also see the [Git +comparison](https://martinvonz.github.io/jj/latest/git-comparison), which +includes a table of `jj` vs. `git` commands. + +As you become more familiar with Jujutsu, the following resources may be helpful: -The best way to get started is probably to go through -[the tutorial](docs/tutorial.md). Also see the -[Git comparison](docs/git-comparison.md), which includes a table of -`jj` vs. `git` commands. +- The [FAQ](https://martinvonz.github.io/jj/latest/FAQ). +- The [Glossary](https://martinvonz.github.io/jj/latest/glossary). +- The `jj help` command (e.g. `jj help rebase`). -As you become more familiar with Jujutsu, the [FAQ](docs/FAQ.md) may help. +If you are using a **prerelease** version of `jj`, you would want to consult +[the docs for the prerelease (main branch) +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 +the header of the website when you scroll to the top of any page. ## Features ### Compatible with Git -Jujutsu has two [backends](docs/glossary.md#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 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. [^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 @@ -72,8 +87,8 @@ add functionality that cannot easily be added to the Git backend. You can even have a ["co-located" local -repository](docs/git-compatibility.md#co-located-jujutsugit-repos) where you can -use both `jj` and `git` commands interchangeably. +repository](https://martinvonz.github.io/jj/latest/git-compatibility#co-located-jujutsugit-repos) +where you can use both `jj` and `git` commands interchangeably. ### The working copy is automatically committed @@ -112,13 +127,14 @@ necessarily have to be the most recent operation). ### Conflicts can be recorded in commits -If an operation results in [conflicts](docs/glossary.md#conflict), information -about those conflicts will be recorded in the commit(s). The operation will -succeed. You can then resolve the conflicts later. One consequence of this -design is that there's no need to continue interrupted operations. Instead, you -get a single workflow for resolving conflicts, regardless of which command -caused them. This design also lets Jujutsu rebase merge commits correctly -(unlike both Git and Mercurial). +If an operation results in +[conflicts](https://martinvonz.github.io/jj/latest/glossary#conflict), +information about those conflicts will be recorded in the commit(s). The +operation will succeed. You can then resolve the conflicts later. One +consequence of this design is that there's no need to continue interrupted +operations. Instead, you get a single workflow for resolving conflicts, +regardless of which command caused them. This design also lets Jujutsu rebase +merge commits correctly (unlike both Git and Mercurial). Basic conflict resolution: @@ -163,4 +179,4 @@ scripts if requested. ## Related work There are several tools trying to solve similar problems as Jujutsu. See -[related work](docs/related-work.md) for details. +[related work](https://martinvonz.github.io/jj/latest/related-work) for details. diff --git a/docs/contributing.md b/docs/contributing.md index e7ecd6bfc7..239c067232 100644 --- a/docs/contributing.md +++ b/docs/contributing.md @@ -58,6 +58,35 @@ This project follows [Google's Open Source Community Guidelines](https://opensource.google/conduct/). +## Contributing to the documentation + +We appreciate [bug +reports](https://github.com/martinvonz/jj/issues/new?template=bug_report.md) +about any problems, however small, lurking in [our documentation +website](https://martinvonz.github.io/jj/prerelease) or in the `jj help +` docs. If a part of the bug report template does not apply, you can +just delete it. + +Before reporting a problem with the documentation website, we'd appreciate it if +you could check that the problem still exists in the "prerelease" version of the +documentation (as opposed to the docs for one of the released versions of `jj`). +You can use the version switcher in the top-left of the website to do so. + +If you are willing to make a PR fixing a documentation problem, even better! + +The documentation website sources are Markdown files located in the [`docs/` +directory](https://github.com/martinvonz/jj/tree/main/docs). You do not need to +know Rust to work with them. See below for [instructions on how to preview the +HTML docs](#previewing-the-html-documentation) as you edit the Markdown files. +Doing so is optional, but recommended. + +The `jj help` docs are sourced from the "docstring" comments inside the Rust +sources, currently from the [`cli/src/commands` +directory](https://github.com/martinvonz/jj/tree/main/cli/src/commands). Working +on them requires setting up a Rust development environment, as described +below, and may occasionally require adjusting a test. + + ## Learning Rust In addition to the [Rust Book](https://doc.rust-lang.org/book/) and the other @@ -65,10 +94,6 @@ excellent resources at , we recommend the ["Comprehensive Rust" mini-course](https://google.github.io/comprehensive-rust/) for an overview, especially if you are familiar with C++. - - ## Setting up a development environment To develop `jj`, the mandatory steps are simply @@ -137,9 +162,8 @@ These are listed roughly in order of decreasing importance. ## Previewing the HTML documentation -The documentation for `jj` is automatically published to the website -. At the moment, this is experimental, -but we hope to advertise this website to our users soon. +The documentation for `jj` is automatically published to the website at +. When editing documentation, we'd appreciate it if you checked that the result will look as expected when published to the website.