From 51b3cc151eb479d9c59e45b5de78dee191354717 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Chris=20W=C3=B6gi?= <789@c-w.li>
Date: Wed, 1 Jun 2022 16:33:03 +0200
Subject: [PATCH] Explain exactly what nix-upgrade nix does

---
 src/nix/upgrade-nix.cc | 2 +-
 src/nix/upgrade-nix.md | 9 ++++++---
 2 files changed, 7 insertions(+), 4 deletions(-)

diff --git a/src/nix/upgrade-nix.cc b/src/nix/upgrade-nix.cc
index 17a5a77ee..2d2453395 100644
--- a/src/nix/upgrade-nix.cc
+++ b/src/nix/upgrade-nix.cc
@@ -34,7 +34,7 @@ struct CmdUpgradeNix : MixDryRun, StoreCommand
 
     std::string description() override
     {
-        return "upgrade Nix to the latest stable version";
+        return "upgrade Nix to the stable version declared in Nixpkgs";
     }
 
     std::string doc() override
diff --git a/src/nix/upgrade-nix.md b/src/nix/upgrade-nix.md
index 4d27daad9..084c80ba2 100644
--- a/src/nix/upgrade-nix.md
+++ b/src/nix/upgrade-nix.md
@@ -2,7 +2,7 @@ R""(
 
 # Examples
 
-* Upgrade Nix to the latest stable version:
+* Upgrade Nix to the stable version declared in Nixpkgs:
 
   ```console
   # nix upgrade-nix
@@ -16,8 +16,11 @@ R""(
 
 # Description
 
-This command upgrades Nix to the latest version. By default, it
-locates the directory containing the `nix` binary in the `$PATH`
+This command upgrades Nix to the stable version declared in Nixpkgs.
+This stable version is defined in [nix-fallback-paths.nix](https://github.com/NixOS/nixpkgs/raw/master/nixos/modules/installer/tools/nix-fallback-paths.nix)
+and updated manually. It may not always be the latest tagged release.
+
+By default, it locates the directory containing the `nix` binary in the `$PATH`
 environment variable. If that directory is a Nix profile, it will
 upgrade the `nix` package in that profile to the latest stable binary
 release.