From f0fc67882caf3ec0783a2876f561e8bdba7f0031 Mon Sep 17 00:00:00 2001
From: Vladimir Panteleev <git@cy.md>
Date: Tue, 16 Jul 2024 20:26:25 +0000
Subject: [PATCH 1/4] doc: Clarify that nix-shell still uses shell from host
 environment

---
 doc/manual/src/command-ref/nix-shell.md | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/doc/manual/src/command-ref/nix-shell.md b/doc/manual/src/command-ref/nix-shell.md
index ddec30f5b..c0e4452a4 100644
--- a/doc/manual/src/command-ref/nix-shell.md
+++ b/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` / `<nixpkgs>` from `NIX_PATH`, and therefore not
+  affected by `--pure`.
 
 - `--packages` / `-p` *packages*…
 

From 4e5cfa5409ce3f4b3da7766809212d85c841c635 Mon Sep 17 00:00:00 2001
From: Vladimir Panteleev <git@cy.md>
Date: Sat, 20 Jul 2024 16:37:04 +0000
Subject: [PATCH 2/4] doc: Fix NIX_BUILD_SHELL description

---
 doc/manual/src/command-ref/nix-shell.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/doc/manual/src/command-ref/nix-shell.md b/doc/manual/src/command-ref/nix-shell.md
index c0e4452a4..c07789369 100644
--- a/doc/manual/src/command-ref/nix-shell.md
+++ b/doc/manual/src/command-ref/nix-shell.md
@@ -117,8 +117,8 @@ All options not listed here are passed to `nix-store
 - `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.
+  `bash` from `bashInteractive` found in `<nixpkgs>`, falling back to
+  the `bash` found in `PATH` if not found.
 
 {{#include ./env-common.md}}
 

From 4a2b4907ca517165a8f6215006daf6608f3e5c3b Mon Sep 17 00:00:00 2001
From: Vladimir Panteleev <git@cy.md>
Date: Sat, 20 Jul 2024 16:40:40 +0000
Subject: [PATCH 3/4] doc: Add anchor and link to NIX_BUILD_SHELL

---
 doc/manual/src/command-ref/nix-shell.md | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/doc/manual/src/command-ref/nix-shell.md b/doc/manual/src/command-ref/nix-shell.md
index c07789369..7a53eaeec 100644
--- a/doc/manual/src/command-ref/nix-shell.md
+++ b/doc/manual/src/command-ref/nix-shell.md
@@ -89,8 +89,8 @@ All options not listed here are passed to `nix-store
   environment that more closely corresponds to the “real” Nix build. A
   few variables, in particular `HOME`, `USER` and `DISPLAY`, are
   retained.  Note that the shell used to run commands is obtained from
-  `NIX_BUILD_SHELL` / `<nixpkgs>` from `NIX_PATH`, and therefore not
-  affected by `--pure`.
+  [`NIX_BUILD_SHELL`](#env-NIX_BUILD_SHELL) / `<nixpkgs>` from
+  `NIX_PATH`, and therefore not affected by `--pure`.
 
 - `--packages` / `-p` *packages*…
 
@@ -114,7 +114,7 @@ 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` from `bashInteractive` found in `<nixpkgs>`, falling back to

From e453e037dfa2c3ea0303d6877e4a1cb60a4fd20a Mon Sep 17 00:00:00 2001
From: Vladimir Panteleev <git@cy.md>
Date: Sat, 20 Jul 2024 17:28:42 +0000
Subject: [PATCH 4/4] doc: Add example of default shell trickiness

---
 doc/manual/src/command-ref/nix-shell.md | 17 +++++++++++++++++
 1 file changed, 17 insertions(+)

diff --git a/doc/manual/src/command-ref/nix-shell.md b/doc/manual/src/command-ref/nix-shell.md
index 7a53eaeec..7e7b2dcfa 100644
--- a/doc/manual/src/command-ref/nix-shell.md
+++ b/doc/manual/src/command-ref/nix-shell.md
@@ -120,6 +120,23 @@ All options not listed here are passed to `nix-store
   `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}}
 
 # Examples