Merge e453e037df into 806a91f7bf

doc/manual/src/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,28 @@ All options not listed here are passed to `nix-store
 
 # Environment variables
 
-- `NIX_BUILD_SHELL`
+- <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` found in `<nixpkgs>`, falling back to the `bash` found in
-  `PATH` if not found.
+  `bash` from `bashInteractive` found in `<nixpkgs>`, falling back to
+  the `bash` found in `PATH` if not found.
+
+  Note that the default shell obtained using the method above may not
+  necessarily be the same as any shells requested in *path*. For
+  example, consider:
+
+  ```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;
+  }
+  ```
+
+  Despite `--pure`, the above will not result in a fully reproducible
+  shell environment.
 
 {{#include ./env-common.md}}