Inconsistent installation instructions

[waldyrious]

After hearing about Nix for a while, I decided to try it out. I managed to install the package manager on my non-NixOS system, but once I started exploring the documentation a bit more, I noticed a few similar, but not identical patterns in how it's recommended to fetch and run the installation script. This is what I managed to collect:

• https://nixos.org/manual/nix/stable/#ch-installing-binary (source):
  curl -L https://nixos.org/nix/install | sh -s
• https://nixos.org/manual/nix/stable/#chap-quick-start (source):
  bash <(curl -L https://nixos.org/nix/install)
• https://nixos.org/manual/nix/stable/#ch-env-variables (source):
  sh <(curl -L https://nixos.org/nix/install)
• https://nixos.org/manual/nixos/stable/#sec-installing-from-other-distro (source):
  curl -L https://nixos.org/nix/install | sh
• https://nixos.org/guides/install-nix.html (source?):
  sh <(curl -L https://nixos.org/nix/install) --daemon
• https://nixos.org/guides/nix-pills/install-on-your-running-system.html (source):
  curl -L https://nixos.org/nix/install | sh
• https://nixos.org/download.html (source):
  curl -L https://nixos.org/nix/install | sh
• NixOS/nixpkgs: default.nix:
  curl -L https://nixos.org/nix/install | sh
• scripts/install-multi-user.sh:
  curl -L https://nixos.org/nix/install | sh
• README.md:
  curl -L https://nixos.org/nix/install | sh

Setting aside the large number of near-duplicated instructions spread across multiple places (which I'm sure is a burden on both users and contributors/maintainers), it's a little concerning how the recommended process varies slightly from place to place.

Which of the invocation methods is the preferred one? These instructions should all be aligned to follow a single pattern.

Even better: it would be nice if these instructions were consolidated in only a handful of places, and the other ones linked to them, to avoid the duplication and to prevent them from getting out of sync.

[abathur]

It would be great to get these single-sourced.

It would be extra great if the same single sources were also used as cases in the install tests. Ideally, each documented install instruction would be under test for every shell we intend to support. (I don't mean to saddle single-sourcing with all of this. A good approach should make it easy; a great approach might do one to demonstrate compatibility?)

---

Just connecting dots/contextualizing a bit:

• I'm too new (and don't know cross-shell compat well enough) to understand this firsthand, but I suspect the curl | sh -s form is the one that should win out. My sense of forms/history from spelunking is:
  • In deeper history curl | sh was the main form.
  • I think the sh <(curl) form started spreading once the official installer supported multi-user since you can append flags like --daemon or --no-daemon without a form change (i.e., this form is less of a stumbling block for people who don't know or have been traumatized by shell).
  • Starting around June 2020, I think the need to add a special flag for macOS installs on Catalina+ (and all of the installer problem reports surrounding that) accelerated the trend towards sh <(curl) forms to avoid the unnecessary papercut.
  • Make install documentation fish-friendly #4985 recently proposed the curl | sh -s form first on the OPs list for compat with fish shell. (I assume this is a good reason for it to win out, but I haven't tried it yet myself and its track record as a recommendation is short.)
• It's a little more complex (and even more wrong 😅) than the initial list presents. The (unstable) manual in master has been translated to Markdown, but the (stable) manual in 2.3-maintenance is still in docbook/xml.
  • The first 3 Nix manual links here are to the stable copy, while the sources linked for those are the unstable markdown source in master.
  • The 2.3 series and this bifurcation have lived long enough that the text itself is also diverging somewhat. I know I myself made substantive changes in darwin: encrypt nix volume if filevault is enabled #4289 that aren't reflected in 2.3-maintenance, and that at least some changes (such as the ones in Make install documentation fish-friendly #4985) have been applied in 2.3-maintenance but not in master.
  • A quick (soon) fix should normalize both copies.
  • A slower fix can probably go into master (Eelco described plans to cut a new release from master soon), but it should still look out for divergences between the sources.

[stale]

I marked this as stale due to inactivity. → More info