From 21f4015cbf1b21709fe649a12657722fc0bab404 Mon Sep 17 00:00:00 2001
From: Ilya Grigoriev <ilyagr@users.noreply.github.com>
Date: Sun, 10 Sep 2023 22:03:41 -0700
Subject: [PATCH] install-and-setup.md: explain how to compile the latest
 release

Also a few minor updates.
---
 docs/install-and-setup.md | 60 ++++++++++++++++++++++++++++++---------
 1 file changed, 47 insertions(+), 13 deletions(-)

diff --git a/docs/install-and-setup.md b/docs/install-and-setup.md
index 82cb060586..0dd94a1a6e 100644
--- a/docs/install-and-setup.md
+++ b/docs/install-and-setup.md
@@ -3,13 +3,17 @@
 
 ## 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).
+### Download pre-built binaries for a release
 
-### Linux
+There are [pre-built binaries](https://github.com/martinvonz/jj/releases/latest)
+of the last released version of `jj` for Windows, Mac, or Linux (the "musl"
+version should work on all distributions).
+
+If you'd like to install a prerelease version, you'll need to use one of the
+options below.
 
-On most distributions, you'll need to build from source using `cargo` directly.
+
+### Linux
 
 #### Build using `cargo`
 
@@ -20,15 +24,26 @@ packages installed by running something like this:
 sudo apt-get install libssl-dev openssl pkg-config
 ```
 
-Now run:
+Now run either:
 
 ```shell
+# To install the *prerelease* version from the main branch
 cargo install --git https://github.com/martinvonz/jj.git --locked --bin jj jj-cli
 ```
 
+or:
+
+```shell
+# To install the latest release
+cargo install --locked --bin jj jj-cli
+```
+
 #### Nix OS
 
-If you're on Nix OS you can use the flake for this repository.
+If you're on Nix OS you can install a **released** version of `jj` using the
+[nixpkgs `jujutsu` package](https://search.nixos.org/packages?channel=unstable&show=jujutsu).
+
+To install a **prerelease** version, you can use the flake for this repository.
 For example, if you want to run `jj` loaded from the flake, use:
 
 ```shell
@@ -39,6 +54,7 @@ You can also add this flake url to your system input flakes. Or you can
 install the flake to your user profile:
 
 ```shell
+# Installs the prerelease version from the main branch
 nix profile install 'github:martinvonz/jj'
 ```
 
@@ -47,6 +63,7 @@ nix profile install 'github:martinvonz/jj'
 If you use linuxbrew, you can run:
 
 ```shell
+# Installs the latest release
 brew install jj
 ```
 
@@ -57,20 +74,20 @@ brew install jj
 If you use Homebrew, you can run:
 
 ```shell
+# Installs the latest release
 brew install jj
 ```
 
 #### MacPorts
 
-You can also install `jj` via [MacPorts](https://www.macports.org) (as
-the `jujutsu` port):
+You can also install `jj` via [the MacPorts `jujutsu`
+port](https://ports.macports.org/port/jujutsu/):
 
 ```shell
+# Installs the latest release
 sudo port install jujutsu
 ```
 
-([port page](https://ports.macports.org/port/jujutsu/))
-
 #### From Source
 
 You may need to run some or all of these:
@@ -82,20 +99,37 @@ brew install pkg-config
 export PKG_CONFIG_PATH="$(brew --prefix)/opt/openssl@3/lib/pkgconfig"
 ```
 
-Now run:
+Now run either:
 
 ```shell
+# To install the *prerelease* version from the main branch
 cargo install --git https://github.com/martinvonz/jj.git --locked --bin jj jj-cli
 ```
 
+or:
+
+```shell
+# To install the latest release
+cargo install --locked --bin jj jj-cli
+```
+
 ### Windows
 
-Run:
+Run either:
 
 ```shell
+# To install the *prerelease* version from the main branch
 cargo install --git https://github.com/martinvonz/jj.git --locked --bin jj jj-cli --features vendored-openssl
 ```
 
+or:
+
+```shell
+# To install the latest release
+cargo install --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.