doc: Clarify that nix-shell still uses shell from host environment (#…

…8809)

* doc: Clarify that nix-shell still uses shell from host environment

* doc: Fix NIX_BUILD_SHELL description

* doc: Add anchor and link to NIX_BUILD_SHELL

* doc: Add example of default shell trickiness

Co-authored-by: Valentin Gagarin <[email protected]>

doc/manual/source/command-ref/nix-shell.md

@@ -88,7 +88,9 @@ All options not listed here are passed to `nix-store
   cleared before the interactive shell is started, so you get an
   environment that more closely corresponds to the “real” Nix build. A
   few variables, in particular `HOME`, `USER` and `DISPLAY`, are
-  retained.
+  retained.  Note that the shell used to run commands is obtained from
+  [`NIX_BUILD_SHELL`](#env-NIX_BUILD_SHELL) / `<nixpkgs>` from
+  `NIX_PATH`, and therefore not affected by `--pure`.
 
 - `--packages` / `-p` *packages*…
 
@@ -112,11 +114,30 @@ All options not listed here are passed to `nix-store
 
 # Environment variables
 
-- `NIX_BUILD_SHELL`
-
-  Shell used to start the interactive environment. Defaults to the
-  `bash` found in `<nixpkgs>`, falling back to the `bash` found in
-  `PATH` if not found.
+- <span id="env-NIX_BUILD_SHELL">[`NIX_BUILD_SHELL`](#env-NIX_BUILD_SHELL)</span>
+
+  Shell used to start the interactive environment.
+  Defaults to the `bash` from `bashInteractive` found in `<nixpkgs>`, falling back to the `bash` found in `PATH` if not found.
+
+  > **Note**
+  >
+  > The shell obtained using this method may not necessarily be the same as any shells requested in *path*.
+
+  <!-- -->
+
+  > **Example
+  >
+  >  Despite `--pure`, this invocation will not result in a fully reproducible shell environment:
+  >
+  > ```nix
+  > #!/usr/bin/env -S nix-shell --pure
+  > let
+  >   pkgs = import (fetchTarball "https://github.com/NixOS/nixpkgs/archive/854fdc68881791812eddd33b2fed94b954979a8e.tar.gz") {};
+  > in
+  > pkgs.mkShell {
+  >   buildInputs = pkgs.bashInteractive;
+  > }
+  > ```
 
 {{#include ./env-common.md}}