From 64140c34b782b75fdc19b9b9acf2576ef00a87d6 Mon Sep 17 00:00:00 2001 From: Ilya Grigoriev Date: Sun, 13 Aug 2023 00:31:20 -0700 Subject: [PATCH] docs: Move installation instructions from README to docs/ This allows the tutorial to reference them and will make it easier to have different instructions for different versions. We can later restore some instructions to the README, but I think this is important since the installation instructions do change in important (even if slight) ways from time to time. --- README.md | 188 +++----------------------------------- docs/install-and-setup.md | 165 +++++++++++++++++++++++++++++++++ docs/tutorial.md | 2 +- 3 files changed, 180 insertions(+), 175 deletions(-) create mode 100644 docs/install-and-setup.md diff --git a/README.md b/README.md index 08c35b7be..90f43fb57 100644 --- a/README.md +++ b/README.md @@ -6,10 +6,8 @@ - [Disclaimer](#disclaimer) - [Introduction](#introduction) -- [Status](#status) -- [Installation](#installation) -- [Command-line completion](#command-line-completion) - [Getting started](#getting-started) +- [Status](#status) - [Related work](#related-work) ## Disclaimer @@ -44,6 +42,19 @@ If you have any questions, please join us on Discord 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`. + +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. + +As you become more familiar with Jujutsu, the [FAQ](docs/FAQ.md) may help. + + ## Features ### Compatible with Git @@ -145,177 +156,6 @@ 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 scripts if requested. -## Installation - -See below for how to build from source. There are also -[pre-built binaries](https://github.com/martinvonz/jj/releases) for Windows, -Mac, or Linux (musl). - -### Linux - -On most distributions, you'll need to build from source using `cargo` directly. - -#### Build using `cargo` - -First make sure that you have the `libssl-dev`, `openssl`, and `pkg-config` -packages installed by running something like this: - -```shell script -sudo apt-get install libssl-dev openssl pkg-config -``` - -Now run: - -```shell script -cargo install --git https://github.com/martinvonz/jj.git --locked --bin jj jj-cli -``` - -#### Nix OS - -If you're on Nix OS you can use the flake for this repository. -For example, if you want to run `jj` loaded from the flake, use: - -```shell script -nix run 'github:martinvonz/jj' -``` - -You can also add this flake url to your system input flakes. Or you can -install the flake to your user profile: - -```shell script -nix profile install 'github:martinvonz/jj' -``` - -#### Homebrew - -If you use linuxbrew, you can run: - -```shell script -brew install jj -``` - -### Mac - -#### Homebrew - -If you use Homebrew, you can run: - -```shell script -brew install jj -``` - -#### MacPorts - -You can also install `jj` via [MacPorts](https://www.macports.org) (as -the `jujutsu` port): - -```shell script -sudo port install jujutsu -``` - -([port page](https://ports.macports.org/port/jujutsu/)) - -#### From Source - -You may need to run some or all of these: - -```shell script -xcode-select --install -brew install openssl -brew install pkg-config -export PKG_CONFIG_PATH="$(brew --prefix)/opt/openssl@3/lib/pkgconfig" -``` - -Now run: - -```shell script -cargo install --git https://github.com/martinvonz/jj.git --locked --bin jj jj-cli -``` - -### Windows - -Run: - -```shell script -cargo install --git https://github.com/martinvonz/jj.git --locked --bin jj jj-cli --features vendored-openssl -``` - -## Initial configuration - -You may want to configure your name and email so commits are made in your name. - -```shell script -$ jj config set --user user.name "Martin von Zweigbergk" -$ jj config set --user user.email "martinvonz@google.com" -``` - -## Command-line completion - -To set up command-line completion, source the output of -`jj util completion --bash/--zsh/--fish` (called `jj debug completion` in -jj <= 0.7.0). Exactly how to source it depends on your shell. - -### Bash - -```shell script -source <(jj util completion) # --bash is the default -``` - -Or, with jj <= 0.7.0: - -```shell script -source <(jj debug completion) # --bash is the default -``` - -### Zsh - -```shell script -autoload -U compinit -compinit -source <(jj util completion --zsh) -``` - -Or, with jj <= 0.7.0: - -```shell script -autoload -U compinit -compinit -source <(jj debug completion --zsh) -``` - -### Fish - -```shell script -jj util completion --fish | source -``` - -Or, with jj <= 0.7.0: - -```shell script -jj debug completion --fish | source -``` - -### Xonsh - -```shell script -source-bash $(jj util completion) -``` - -Or, with jj <= 0.7.0: - -```shell script -source-bash $(jj debug completion) -``` - -## Getting started - -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. - -As you become more familiar with Jujutsu, the [FAQ](docs/FAQ.md) may help. - ## Related work There are several tools trying to solve similar problems as Jujutsu. See diff --git a/docs/install-and-setup.md b/docs/install-and-setup.md new file mode 100644 index 000000000..96f59583d --- /dev/null +++ b/docs/install-and-setup.md @@ -0,0 +1,165 @@ +# Installation and setup + + +## Installation + +See below for how to build from source. There are also +[pre-built binaries](https://github.com/martinvonz/jj/releases) for Windows, +Mac, or Linux (musl). + +### Linux + +On most distributions, you'll need to build from source using `cargo` directly. + +#### Build using `cargo` + +First make sure that you have the `libssl-dev`, `openssl`, and `pkg-config` +packages installed by running something like this: + +```shell script +sudo apt-get install libssl-dev openssl pkg-config +``` + +Now run: + +```shell script +cargo install --git https://github.com/martinvonz/jj.git --locked --bin jj jj-cli +``` + +#### Nix OS + +If you're on Nix OS you can use the flake for this repository. +For example, if you want to run `jj` loaded from the flake, use: + +```shell script +nix run 'github:martinvonz/jj' +``` + +You can also add this flake url to your system input flakes. Or you can +install the flake to your user profile: + +```shell script +nix profile install 'github:martinvonz/jj' +``` + +#### Homebrew + +If you use linuxbrew, you can run: + +```shell script +brew install jj +``` + +### Mac + +#### Homebrew + +If you use Homebrew, you can run: + +```shell script +brew install jj +``` + +#### MacPorts + +You can also install `jj` via [MacPorts](https://www.macports.org) (as +the `jujutsu` port): + +```shell script +sudo port install jujutsu +``` + +([port page](https://ports.macports.org/port/jujutsu/)) + +#### From Source + +You may need to run some or all of these: + +```shell script +xcode-select --install +brew install openssl +brew install pkg-config +export PKG_CONFIG_PATH="$(brew --prefix)/opt/openssl@3/lib/pkgconfig" +``` + +Now run: + +```shell script +cargo install --git https://github.com/martinvonz/jj.git --locked --bin jj jj-cli +``` + +### Windows + +Run: + +```shell script +cargo install --git https://github.com/martinvonz/jj.git --locked --bin jj jj-cli --features vendored-openssl +``` + +## Initial configuration + +You may want to configure your name and email so commits are made in your name. + +```shell script +$ jj config set --user user.name "Martin von Zweigbergk" +$ jj config set --user user.email "martinvonz@google.com" +``` + +## Command-line completion + +To set up command-line completion, source the output of +`jj util completion --bash/--zsh/--fish` (called `jj debug completion` in +jj <= 0.7.0). Exactly how to source it depends on your shell. + +### Bash + +```shell script +source <(jj util completion) # --bash is the default +``` + +Or, with jj <= 0.7.0: + +```shell script +source <(jj debug completion) # --bash is the default +``` + +### Zsh + +```shell script +autoload -U compinit +compinit +source <(jj util completion --zsh) +``` + +Or, with jj <= 0.7.0: + +```shell script +autoload -U compinit +compinit +source <(jj debug completion --zsh) +``` + +### Fish + +```shell script +jj util completion --fish | source +``` + +Or, with jj <= 0.7.0: + +```shell script +jj debug completion --fish | source +``` + +### Xonsh + +```shell script +source-bash $(jj util completion) +``` + +Or, with jj <= 0.7.0: + +```shell script +source-bash $(jj debug completion) +``` + diff --git a/docs/tutorial.md b/docs/tutorial.md index ff0063e99..2caca2e90 100644 --- a/docs/tutorial.md +++ b/docs/tutorial.md @@ -5,7 +5,7 @@ This text assumes that the reader is familiar with Git. ## Preparation If you haven't already, make sure you -[install and configure Jujutsu](../README.md#Installation). +[install and configure Jujutsu](install-and-setup.md). ## Cloning a Git repo