From ba074465ba249da4df0752d0dc53529d0ab1a60d Mon Sep 17 00:00:00 2001
From: Vladimir Panteleev <CyberShadow@users.noreply.github.com>
Date: Thu, 21 Nov 2024 20:08:13 +0000
Subject: [PATCH] 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 <valentin@gagarin.work>
---
 doc/manual/source/command-ref/nix-shell.md | 31 ++++++++++++++++++----
 1 file changed, 26 insertions(+), 5 deletions(-)

diff --git a/doc/manual/source/command-ref/nix-shell.md b/doc/manual/source/command-ref/nix-shell.md
index 69a711bd5..e95db9bea 100644
--- a/doc/manual/source/command-ref/nix-shell.md
+++ b/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`
+- <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.
+  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}}