From 04023360edbeb3477286783b3101a5b53f78021b Mon Sep 17 00:00:00 2001
From: Matthew Bauer <mjbauer95@gmail.com>
Date: Tue, 3 Aug 2021 15:25:15 -0500
Subject: [PATCH 01/25] Evaluate nix-shell -i args relative to script

When writing a shebang script, you expect your path to be relative to
the script, not the cwd. We previously handled this correctly for
relative file paths, but not for expressions.

This handles both -p & -E args. My understanding is this should be
what we want in any cases I can think of - people run scripts from
many different working directories. @edolstra is there any reason to
handle -p args differently in this case?

Fixes #4232
---
 src/nix-build/nix-build.cc | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/src/nix-build/nix-build.cc b/src/nix-build/nix-build.cc
index 75ce12a8c..4120ca3cf 100644
--- a/src/nix-build/nix-build.cc
+++ b/src/nix-build/nix-build.cc
@@ -298,7 +298,9 @@ static void main_nix_build(int argc, char * * argv)
     else
         for (auto i : left) {
             if (fromArgs)
-                exprs.push_back(state->parseExprFromString(std::move(i), state->rootPath(CanonPath::fromCwd())));
+                exprs.push_back(state->parseExprFromString(
+                    std::move(i),
+                    state->rootPath(CanonPath::fromCwd(inShebang ? dirOf(script) : "."))));
             else {
                 auto absolute = i;
                 try {
@@ -311,7 +313,7 @@ static void main_nix_build(int argc, char * * argv)
                     /* If we're in a #! script, interpret filenames
                        relative to the script. */
                     exprs.push_back(state->parseExprFromFile(resolveExprPath(state->checkSourcePath(lookupFileArg(*state,
-                                        inShebang && !packages ? absPath(i, absPath(dirOf(script))) : i)))));
+                                        inShebang ? absPath(i, absPath(dirOf(script))) : i)))));
             }
         }
 

From 9a4641146f79d631eb0825c7313dd335715de0d6 Mon Sep 17 00:00:00 2001
From: Tom Bereknyei <tomberek@gmail.com>
Date: Sat, 25 Nov 2023 19:06:45 -0500
Subject: [PATCH 02/25] tests: ensure nix-shell uses relative paths for
 expressions

---
 tests/functional/nix-shell.sh | 10 ++++++++++
 1 file changed, 10 insertions(+)

diff --git a/tests/functional/nix-shell.sh b/tests/functional/nix-shell.sh
index 13403fadb..702d3a6b5 100644
--- a/tests/functional/nix-shell.sh
+++ b/tests/functional/nix-shell.sh
@@ -59,6 +59,16 @@ chmod a+rx $TEST_ROOT/shell.shebang.sh
 output=$($TEST_ROOT/shell.shebang.sh abc def)
 [ "$output" = "foo bar abc def" ]
 
+# Test nix-shell shebang mode with an alternate working directory
+sed -e "s|@ENV_PROG@|$(type -P env)|" shell.shebang.expr > $TEST_ROOT/shell.shebang.expr
+chmod a+rx $TEST_ROOT/shell.shebang.expr
+# Should fail due to expressions using relative path
+! $TEST_ROOT/shell.shebang.expr bar
+cp shell.nix config.nix $TEST_ROOT
+# Should succeed
+output=$($TEST_ROOT/shell.shebang.expr bar)
+[ "$output" = '-e load(ARGV.shift) -- '"$TEST_ROOT"'/shell.shebang.expr bar' ]
+
 # Test nix-shell shebang mode again with metacharacters in the filename.
 # First word of filename is chosen to not match any file in the test root.
 sed -e "s|@ENV_PROG@|$(type -P env)|" shell.shebang.sh > $TEST_ROOT/spaced\ \\\'\"shell.shebang.sh

From f66f498bd43efaa6883f12ca5988a282eef09697 Mon Sep 17 00:00:00 2001
From: Tom Bereknyei <tomberek@gmail.com>
Date: Sat, 25 Nov 2023 19:07:29 -0500
Subject: [PATCH 03/25] notes: document change in nix-shell behavior

---
 doc/manual/rl-next/shebang-relative.md | 8 ++++++++
 1 file changed, 8 insertions(+)
 create mode 100644 doc/manual/rl-next/shebang-relative.md

diff --git a/doc/manual/rl-next/shebang-relative.md b/doc/manual/rl-next/shebang-relative.md
new file mode 100644
index 000000000..dbda0db4c
--- /dev/null
+++ b/doc/manual/rl-next/shebang-relative.md
@@ -0,0 +1,8 @@
+synopsis: ensure nix-shell shebang uses relative path
+prs: #5088
+description: {
+
+`nix-shell` shebangs use the script file's relative location to resolve relative paths to files passed as command line arguments, but expression arguments were still evaluated using the current working directory as a base path.
+The new behavior is that evalutations are performed relative to the script.
+
+}

From 13181356fc6fc3fa7e5f8ac98da6a2f28cb50003 Mon Sep 17 00:00:00 2001
From: Robert Hensing <robert@roberthensing.nl>
Date: Sat, 6 Jul 2024 20:01:46 +0200
Subject: [PATCH 04/25] Refactor: rename runEnv -> isNixShell

---
 src/nix-build/nix-build.cc | 22 +++++++++++-----------
 1 file changed, 11 insertions(+), 11 deletions(-)

diff --git a/src/nix-build/nix-build.cc b/src/nix-build/nix-build.cc
index 57630c8c3..d0b3b4f9f 100644
--- a/src/nix-build/nix-build.cc
+++ b/src/nix-build/nix-build.cc
@@ -93,7 +93,7 @@ static std::vector<std::string> shellwords(const std::string & s)
 static void main_nix_build(int argc, char * * argv)
 {
     auto dryRun = false;
-    auto runEnv = std::regex_search(argv[0], std::regex("nix-shell$"));
+    auto isNixShell = std::regex_search(argv[0], std::regex("nix-shell$"));
     auto pure = false;
     auto fromArgs = false;
     auto packages = false;
@@ -107,7 +107,7 @@ static void main_nix_build(int argc, char * * argv)
     std::string envCommand; // interactive shell
     Strings envExclude;
 
-    auto myName = runEnv ? "nix-shell" : "nix-build";
+    auto myName = isNixShell ? "nix-shell" : "nix-build";
 
     auto inShebang = false;
     std::string script;
@@ -132,7 +132,7 @@ static void main_nix_build(int argc, char * * argv)
     // Heuristic to see if we're invoked as a shebang script, namely,
     // if we have at least one argument, it's the name of an
     // executable file, and it starts with "#!".
-    if (runEnv && argc > 1) {
+    if (isNixShell && argc > 1) {
         script = argv[1];
         try {
             auto lines = tokenizeString<Strings>(readFile(script), "\n");
@@ -186,9 +186,9 @@ static void main_nix_build(int argc, char * * argv)
             dryRun = true;
 
         else if (*arg == "--run-env") // obsolete
-            runEnv = true;
+            isNixShell = true;
 
-        else if (runEnv && (*arg == "--command" || *arg == "--run")) {
+        else if (isNixShell && (*arg == "--command" || *arg == "--run")) {
             if (*arg == "--run")
                 interactive = false;
             envCommand = getArg(*arg, arg, end) + "\nexit";
@@ -206,7 +206,7 @@ static void main_nix_build(int argc, char * * argv)
         else if (*arg == "--pure") pure = true;
         else if (*arg == "--impure") pure = false;
 
-        else if (runEnv && (*arg == "--packages" || *arg == "-p"))
+        else if (isNixShell && (*arg == "--packages" || *arg == "-p"))
             packages = true;
 
         else if (inShebang && *arg == "-i") {
@@ -266,7 +266,7 @@ static void main_nix_build(int argc, char * * argv)
     auto autoArgs = myArgs.getAutoArgs(*state);
 
     auto autoArgsWithInNixShell = autoArgs;
-    if (runEnv) {
+    if (isNixShell) {
         auto newArgs = state->buildBindings(autoArgsWithInNixShell->size() + 1);
         newArgs.alloc("inNixShell").mkBool(true);
         for (auto & i : *autoArgs) newArgs.insert(i);
@@ -282,13 +282,13 @@ static void main_nix_build(int argc, char * * argv)
         fromArgs = true;
         left = {joined.str()};
     } else if (!fromArgs) {
-        if (left.empty() && runEnv && pathExists("shell.nix"))
+        if (left.empty() && isNixShell && pathExists("shell.nix"))
             left = {"shell.nix"};
         if (left.empty())
             left = {"default.nix"};
     }
 
-    if (runEnv)
+    if (isNixShell)
         setEnv("IN_NIX_SHELL", pure ? "pure" : "impure");
 
     PackageInfos drvs;
@@ -330,7 +330,7 @@ static void main_nix_build(int argc, char * * argv)
 
         std::function<bool(const Value & v)> takesNixShellAttr;
         takesNixShellAttr = [&](const Value & v) {
-            if (!runEnv) {
+            if (!isNixShell) {
                 return false;
             }
             bool add = false;
@@ -381,7 +381,7 @@ static void main_nix_build(int argc, char * * argv)
             store->buildPaths(paths, buildMode, evalStore);
     };
 
-    if (runEnv) {
+    if (isNixShell) {
         if (drvs.size() != 1)
             throw UsageError("nix-shell requires a single derivation");
 

From 5c367ece895601a90ef4f38547e7cd84ce5d83d5 Mon Sep 17 00:00:00 2001
From: Robert Hensing <robert@roberthensing.nl>
Date: Sat, 6 Jul 2024 20:03:30 +0200
Subject: [PATCH 05/25] Refactor: rename left -> remainingArgs

---
 src/nix-build/nix-build.cc | 18 +++++++++---------
 1 file changed, 9 insertions(+), 9 deletions(-)

diff --git a/src/nix-build/nix-build.cc b/src/nix-build/nix-build.cc
index d0b3b4f9f..faa9e5fae 100644
--- a/src/nix-build/nix-build.cc
+++ b/src/nix-build/nix-build.cc
@@ -100,7 +100,7 @@ static void main_nix_build(int argc, char * * argv)
     // Same condition as bash uses for interactive shells
     auto interactive = isatty(STDIN_FILENO) && isatty(STDERR_FILENO);
     Strings attrPaths;
-    Strings left;
+    Strings remainingArgs;
     BuildMode buildMode = bmNormal;
     bool readStdin = false;
 
@@ -246,7 +246,7 @@ static void main_nix_build(int argc, char * * argv)
             return false;
 
         else
-            left.push_back(*arg);
+            remainingArgs.push_back(*arg);
 
         return true;
     });
@@ -276,16 +276,16 @@ static void main_nix_build(int argc, char * * argv)
     if (packages) {
         std::ostringstream joined;
         joined << "{...}@args: with import <nixpkgs> args; (pkgs.runCommandCC or pkgs.runCommand) \"shell\" { buildInputs = [ ";
-        for (const auto & i : left)
+        for (const auto & i : remainingArgs)
             joined << '(' << i << ") ";
         joined << "]; } \"\"";
         fromArgs = true;
-        left = {joined.str()};
+        remainingArgs = {joined.str()};
     } else if (!fromArgs) {
-        if (left.empty() && isNixShell && pathExists("shell.nix"))
-            left = {"shell.nix"};
-        if (left.empty())
-            left = {"default.nix"};
+        if (remainingArgs.empty() && isNixShell && pathExists("shell.nix"))
+            remainingArgs = {"shell.nix"};
+        if (remainingArgs.empty())
+            remainingArgs = {"default.nix"};
     }
 
     if (isNixShell)
@@ -299,7 +299,7 @@ static void main_nix_build(int argc, char * * argv)
     if (readStdin)
         exprs = {state->parseStdin()};
     else
-        for (auto i : left) {
+        for (auto i : remainingArgs) {
             if (fromArgs)
                 exprs.push_back(state->parseExprFromString(std::move(i), state->rootPath(".")));
             else {

From e9479b272faaf00068348e7df8de7f50dce58113 Mon Sep 17 00:00:00 2001
From: Robert Hensing <robert@roberthensing.nl>
Date: Sat, 6 Jul 2024 20:51:45 +0200
Subject: [PATCH 06/25] nix-build.cc: Refactor: extract baseDir variable

---
 src/nix-build/nix-build.cc | 7 +++++--
 1 file changed, 5 insertions(+), 2 deletions(-)

diff --git a/src/nix-build/nix-build.cc b/src/nix-build/nix-build.cc
index faa9e5fae..648917444 100644
--- a/src/nix-build/nix-build.cc
+++ b/src/nix-build/nix-build.cc
@@ -310,14 +310,17 @@ static void main_nix_build(int argc, char * * argv)
                 auto [path, outputNames] = parsePathWithOutputs(absolute);
                 if (evalStore->isStorePath(path) && hasSuffix(path, ".drv"))
                     drvs.push_back(PackageInfo(*state, evalStore, absolute));
-                else
+                else {
                     /* If we're in a #! script, interpret filenames
                        relative to the script. */
+                    auto baseDir = inShebang && !packages ? absPath(i, absPath(dirOf(script))) : i;
+
                     exprs.push_back(
                         state->parseExprFromFile(
                             resolveExprPath(
                                 lookupFileArg(*state,
-                                    inShebang && !packages ? absPath(i, absPath(dirOf(script))) : i))));
+                                    baseDir))));
+                }
             }
         }
 

From 76245ffbebc8466ac17d241fceda6dcb9ec7c23e Mon Sep 17 00:00:00 2001
From: Robert Hensing <robert@roberthensing.nl>
Date: Sat, 6 Jul 2024 20:55:27 +0200
Subject: [PATCH 07/25] nix-build.cc: Refactor: extract sourcePath,
 resolvedPath variables

---
 src/nix-build/nix-build.cc | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/src/nix-build/nix-build.cc b/src/nix-build/nix-build.cc
index 648917444..e873f712b 100644
--- a/src/nix-build/nix-build.cc
+++ b/src/nix-build/nix-build.cc
@@ -315,11 +315,11 @@ static void main_nix_build(int argc, char * * argv)
                        relative to the script. */
                     auto baseDir = inShebang && !packages ? absPath(i, absPath(dirOf(script))) : i;
 
-                    exprs.push_back(
-                        state->parseExprFromFile(
-                            resolveExprPath(
-                                lookupFileArg(*state,
-                                    baseDir))));
+                    auto sourcePath = lookupFileArg(*state,
+                                    baseDir);
+                    auto resolvedPath = resolveExprPath(sourcePath);
+
+                    exprs.push_back(state->parseExprFromFile(resolvedPath));
                 }
             }
         }

From 32fb127b9cbaf833027e646de5ee5198a62b6995 Mon Sep 17 00:00:00 2001
From: Robert Hensing <robert@roberthensing.nl>
Date: Sat, 6 Jul 2024 22:58:15 +0200
Subject: [PATCH 08/25] Add legacy setting:
 nix-shell-always-looks-for-shell-nix

---
 src/libcmd/common-eval-args.cc |  7 +++++++
 src/libcmd/common-eval-args.hh |  6 ++++++
 src/libcmd/meson.build         |  1 +
 src/nix-build/nix-build.cc     | 23 ++++++++++++++++++-----
 tests/functional/nix-shell.sh  |  9 +++++++++
 5 files changed, 41 insertions(+), 5 deletions(-)

diff --git a/src/libcmd/common-eval-args.cc b/src/libcmd/common-eval-args.cc
index 01546f9a0..62745b681 100644
--- a/src/libcmd/common-eval-args.cc
+++ b/src/libcmd/common-eval-args.cc
@@ -11,6 +11,8 @@
 #include "command.hh"
 #include "tarball.hh"
 #include "fetch-to-store.hh"
+#include "compatibility-settings.hh"
+#include "eval-settings.hh"
 
 namespace nix {
 
@@ -33,6 +35,11 @@ EvalSettings evalSettings {
 
 static GlobalConfig::Register rEvalSettings(&evalSettings);
 
+CompatibilitySettings compatibilitySettings {};
+
+static GlobalConfig::Register rCompatibilitySettings(&compatibilitySettings);
+
+
 MixEvalArgs::MixEvalArgs()
 {
     addFlag({
diff --git a/src/libcmd/common-eval-args.hh b/src/libcmd/common-eval-args.hh
index 189abf0ed..8d303ee7c 100644
--- a/src/libcmd/common-eval-args.hh
+++ b/src/libcmd/common-eval-args.hh
@@ -13,6 +13,7 @@ namespace nix {
 class Store;
 class EvalState;
 struct EvalSettings;
+struct CompatibilitySettings;
 class Bindings;
 struct SourcePath;
 
@@ -21,6 +22,11 @@ struct SourcePath;
  */
 extern EvalSettings evalSettings;
 
+/**
+ * Settings that control behaviors that have changed since Nix 2.3.
+ */
+extern CompatibilitySettings compatibilitySettings;
+
 struct MixEvalArgs : virtual Args, virtual MixRepair
 {
     static constexpr auto category = "Common evaluation options";
diff --git a/src/libcmd/meson.build b/src/libcmd/meson.build
index d9a90508a..2c8a9fa33 100644
--- a/src/libcmd/meson.build
+++ b/src/libcmd/meson.build
@@ -97,6 +97,7 @@ headers = [config_h] + files(
   'command-installable-value.hh',
   'command.hh',
   'common-eval-args.hh',
+  'compatibility-settings.hh',
   'editor-for.hh',
   'installable-attr-path.hh',
   'installable-derived-path.hh',
diff --git a/src/nix-build/nix-build.cc b/src/nix-build/nix-build.cc
index 30cc86456..d37b16bdc 100644
--- a/src/nix-build/nix-build.cc
+++ b/src/nix-build/nix-build.cc
@@ -26,6 +26,7 @@
 #include "legacy.hh"
 #include "users.hh"
 #include "network-proxy.hh"
+#include "compatibility-settings.hh"
 
 using namespace nix;
 using namespace std::string_literals;
@@ -100,7 +101,13 @@ static SourcePath resolveShellExprPath(SourcePath path)
     auto resolvedOrDir = resolveExprPath(path, false);
     if (resolvedOrDir.resolveSymlinks().lstat().type == SourceAccessor::tDirectory) {
         if ((resolvedOrDir / "shell.nix").pathExists()) {
-            return resolvedOrDir / "shell.nix";
+            if (compatibilitySettings.nixShellAlwaysLooksForShellNix) {
+                return resolvedOrDir / "shell.nix";
+            } else {
+                warn("Skipping '%1%', because the setting '%2%' is disabled. This is a deprecated behavior. Consider enabling '%2%'.",
+                    resolvedOrDir / "shell.nix",
+                    "nix-shell-always-looks-for-shell-nix");
+            }
         }
         if ((resolvedOrDir / "default.nix").pathExists()) {
             return resolvedOrDir / "default.nix";
@@ -302,11 +309,17 @@ static void main_nix_build(int argc, char * * argv)
         fromArgs = true;
         remainingArgs = {joined.str()};
     } else if (!fromArgs && remainingArgs.empty()) {
-        remainingArgs = {"."};
+        if (isNixShell && !compatibilitySettings.nixShellAlwaysLooksForShellNix && std::filesystem::exists("shell.nix")) {
+            // If we're in 2.3 compatibility mode, we need to look for shell.nix
+            // now, because it won't be done later.
+            remainingArgs = {"shell.nix"};
+        } else {
+            remainingArgs = {"."};
 
-        // Instead of letting it throw later, we throw here to give a more relevant error message
-        if (isNixShell && !std::filesystem::exists("shell.nix") && !std::filesystem::exists("default.nix"))
-            throw Error("no argument specified and no '%s' or '%s' file found in the working directory", "shell.nix", "default.nix");
+            // Instead of letting it throw later, we throw here to give a more relevant error message
+            if (isNixShell && !std::filesystem::exists("shell.nix") && !std::filesystem::exists("default.nix"))
+                throw Error("no argument specified and no '%s' or '%s' file found in the working directory", "shell.nix", "default.nix");
+        }
     }
 
     if (isNixShell)
diff --git a/tests/functional/nix-shell.sh b/tests/functional/nix-shell.sh
index b7a7db27c..2a1d556dd 100755
--- a/tests/functional/nix-shell.sh
+++ b/tests/functional/nix-shell.sh
@@ -21,6 +21,10 @@ output=$(nix-shell --pure "$shellDotNix" -A shellDrv --run \
 
 [ "$output" = " - foo - bar - true" ]
 
+output=$(nix-shell --pure "$shellDotNix" -A shellDrv --option nix-shell-always-looks-for-shell-nix false --run \
+    'echo "$IMPURE_VAR - $VAR_FROM_STDENV_SETUP - $VAR_FROM_NIX - $TEST_inNixShell"')
+[ "$output" = " - foo - bar - true" ]
+
 # Test --keep
 output=$(nix-shell --pure --keep SELECTED_IMPURE_VAR "$shellDotNix" -A shellDrv --run \
     'echo "$IMPURE_VAR - $VAR_FROM_STDENV_SETUP - $VAR_FROM_NIX - $SELECTED_IMPURE_VAR"')
@@ -101,6 +105,11 @@ nix-shell $TEST_ROOT/lookup-test -A shellDrv --run 'echo "it works"' | grepQuiet
 # https://github.com/NixOS/nix/issues/4529
 nix-shell -I "testRoot=$TEST_ROOT" '<testRoot/lookup-test>' -A shellDrv --run 'echo "it works"' | grepQuiet "it works"
 
+expectStderr 1 nix-shell $TEST_ROOT/lookup-test -A shellDrv --run 'echo "it works"' --option nix-shell-always-looks-for-shell-nix false \
+  | grepQuiet -F "do not load default.nix!" # we did, because we chose to enable legacy behavior
+expectStderr 1 nix-shell $TEST_ROOT/lookup-test -A shellDrv --run 'echo "it works"' --option nix-shell-always-looks-for-shell-nix false \
+  | grepQuiet "Skipping .*lookup-test/shell\.nix.*, because the setting .*nix-shell-always-looks-for-shell-nix.* is disabled. This is a deprecated behavior\. Consider enabling .*nix-shell-always-looks-for-shell-nix.*"
+
 (
   cd $TEST_ROOT/empty;
   expectStderr 1 nix-shell | \

From a22f8b5276162a87072eee7f0febc0a216f4fa9b Mon Sep 17 00:00:00 2001
From: Robert Hensing <robert@roberthensing.nl>
Date: Sat, 6 Jul 2024 23:02:32 +0200
Subject: [PATCH 09/25] rl-next: Add note about shell.nix lookups

---
 .../rl-next/nix-shell-looks-for-shell-nix.md  | 26 +++++++++++++++++++
 1 file changed, 26 insertions(+)
 create mode 100644 doc/manual/rl-next/nix-shell-looks-for-shell-nix.md

diff --git a/doc/manual/rl-next/nix-shell-looks-for-shell-nix.md b/doc/manual/rl-next/nix-shell-looks-for-shell-nix.md
new file mode 100644
index 000000000..1f44ba33c
--- /dev/null
+++ b/doc/manual/rl-next/nix-shell-looks-for-shell-nix.md
@@ -0,0 +1,26 @@
+---
+synopsis: "`nix-shell <directory>` looks for `shell.nix`"
+significance: significant
+issues:
+- 496
+- 2279
+- 4529
+- 5431
+- 11053
+---
+
+`nix-shell $x` now looks for `$x/shell.nix` when `$x` resolves to a directory.
+
+Although this might be seen as a breaking change, its primarily interactive usage makes it a minor issue.
+This adjustment addresses a commonly reported problem.
+
+This also applies to `nix-shell` shebang scripts. Consider the following example:
+
+```shell
+#!/usr/bin/env nix-shell
+#!nix-shell -i bash
+```
+
+This will now load `shell.nix` from the script's directory, if it exists; `default.nix` otherwise.
+
+The old behavior can be opted into by setting the option [`nix-shell-always-looks-for-shell-nix`](@docroot@/command-ref/conf-file.md#conf-nix-shell-always-looks-for-shell-nix) to `false`.

From b865625a8eab8382e1643605594e9db23271c2e5 Mon Sep 17 00:00:00 2001
From: Robert Hensing <robert@roberthensing.nl>
Date: Sat, 6 Jul 2024 21:31:24 +0200
Subject: [PATCH 10/25] nix-shell: Look for shell.nix when directory is
 specified

---
 src/libexpr/eval.cc           |  4 ++--
 src/libexpr/eval.hh           |  4 +++-
 src/nix-build/nix-build.cc    | 34 ++++++++++++++++++++++-----
 tests/functional/nix-shell.sh | 44 +++++++++++++++++++++++++++++++++++
 tests/functional/shell.nix    | 11 +++++++++
 5 files changed, 88 insertions(+), 9 deletions(-)

diff --git a/src/libexpr/eval.cc b/src/libexpr/eval.cc
index 48ed66883..2a0862123 100644
--- a/src/libexpr/eval.cc
+++ b/src/libexpr/eval.cc
@@ -2650,7 +2650,7 @@ void EvalState::printStatistics()
 }
 
 
-SourcePath resolveExprPath(SourcePath path)
+SourcePath resolveExprPath(SourcePath path, bool addDefaultNix)
 {
     unsigned int followCount = 0, maxFollow = 1024;
 
@@ -2666,7 +2666,7 @@ SourcePath resolveExprPath(SourcePath path)
     }
 
     /* If `path' refers to a directory, append `/default.nix'. */
-    if (path.resolveSymlinks().lstat().type == SourceAccessor::tDirectory)
+    if (addDefaultNix && path.resolveSymlinks().lstat().type == SourceAccessor::tDirectory)
         return path / "default.nix";
 
     return path;
diff --git a/src/libexpr/eval.hh b/src/libexpr/eval.hh
index b84bc9907..e45358055 100644
--- a/src/libexpr/eval.hh
+++ b/src/libexpr/eval.hh
@@ -850,8 +850,10 @@ std::string showType(const Value & v);
 
 /**
  * If `path` refers to a directory, then append "/default.nix".
+ *
+ * @param addDefaultNix Whether to append "/default.nix" after resolving symlinks.
  */
-SourcePath resolveExprPath(SourcePath path);
+SourcePath resolveExprPath(SourcePath path, bool addDefaultNix = true);
 
 /**
  * Whether a URI is allowed, assuming restrictEval is enabled
diff --git a/src/nix-build/nix-build.cc b/src/nix-build/nix-build.cc
index e873f712b..30cc86456 100644
--- a/src/nix-build/nix-build.cc
+++ b/src/nix-build/nix-build.cc
@@ -90,6 +90,26 @@ static std::vector<std::string> shellwords(const std::string & s)
     return res;
 }
 
+/**
+ * Like `resolveExprPath`, but prefers `shell.nix` instead of `default.nix`,
+ * and if `path` was a directory, it checks eagerly whether `shell.nix` or
+ * `default.nix` exist, throwing an error if they don't.
+ */
+static SourcePath resolveShellExprPath(SourcePath path)
+{
+    auto resolvedOrDir = resolveExprPath(path, false);
+    if (resolvedOrDir.resolveSymlinks().lstat().type == SourceAccessor::tDirectory) {
+        if ((resolvedOrDir / "shell.nix").pathExists()) {
+            return resolvedOrDir / "shell.nix";
+        }
+        if ((resolvedOrDir / "default.nix").pathExists()) {
+            return resolvedOrDir / "default.nix";
+        }
+        throw Error("neither '%s' nor '%s' found in '%s'", "shell.nix", "default.nix", resolvedOrDir);
+    }
+    return resolvedOrDir;
+}
+
 static void main_nix_build(int argc, char * * argv)
 {
     auto dryRun = false;
@@ -281,11 +301,12 @@ static void main_nix_build(int argc, char * * argv)
         joined << "]; } \"\"";
         fromArgs = true;
         remainingArgs = {joined.str()};
-    } else if (!fromArgs) {
-        if (remainingArgs.empty() && isNixShell && pathExists("shell.nix"))
-            remainingArgs = {"shell.nix"};
-        if (remainingArgs.empty())
-            remainingArgs = {"default.nix"};
+    } else if (!fromArgs && remainingArgs.empty()) {
+        remainingArgs = {"."};
+
+        // Instead of letting it throw later, we throw here to give a more relevant error message
+        if (isNixShell && !std::filesystem::exists("shell.nix") && !std::filesystem::exists("default.nix"))
+            throw Error("no argument specified and no '%s' or '%s' file found in the working directory", "shell.nix", "default.nix");
     }
 
     if (isNixShell)
@@ -317,7 +338,8 @@ static void main_nix_build(int argc, char * * argv)
 
                     auto sourcePath = lookupFileArg(*state,
                                     baseDir);
-                    auto resolvedPath = resolveExprPath(sourcePath);
+                    auto resolvedPath =
+                        isNixShell ? resolveShellExprPath(sourcePath) : resolveExprPath(sourcePath);
 
                     exprs.push_back(state->parseExprFromFile(resolvedPath));
                 }
diff --git a/tests/functional/nix-shell.sh b/tests/functional/nix-shell.sh
index 2c94705de..b7a7db27c 100755
--- a/tests/functional/nix-shell.sh
+++ b/tests/functional/nix-shell.sh
@@ -91,6 +91,50 @@ sed -e "s|@ENV_PROG@|$(type -P env)|" shell.shebang.nix > $TEST_ROOT/shell.sheba
 chmod a+rx $TEST_ROOT/shell.shebang.nix
 $TEST_ROOT/shell.shebang.nix
 
+mkdir $TEST_ROOT/lookup-test $TEST_ROOT/empty
+
+cp $shellDotNix $TEST_ROOT/lookup-test/shell.nix
+cp config.nix $TEST_ROOT/lookup-test/
+echo 'abort "do not load default.nix!"' > $TEST_ROOT/lookup-test/default.nix
+
+nix-shell $TEST_ROOT/lookup-test -A shellDrv --run 'echo "it works"' | grepQuiet "it works"
+# https://github.com/NixOS/nix/issues/4529
+nix-shell -I "testRoot=$TEST_ROOT" '<testRoot/lookup-test>' -A shellDrv --run 'echo "it works"' | grepQuiet "it works"
+
+(
+  cd $TEST_ROOT/empty;
+  expectStderr 1 nix-shell | \
+    grepQuiet "error.*no argument specified and no .*shell\.nix.* or .*default\.nix.* file found in the working directory"
+)
+
+expectStderr 1 nix-shell -I "testRoot=$TEST_ROOT" '<testRoot/empty>' |
+  grepQuiet "error.*neither .*shell\.nix.* nor .*default\.nix.* found in .*/empty"
+
+cat >$TEST_ROOT/lookup-test/shebangscript <<"EOF"
+#!/usr/bin/env nix-shell
+#!nix-shell -A shellDrv -i bash
+[[ $VAR_FROM_NIX == bar ]]
+echo "script works"
+EOF
+chmod +x $TEST_ROOT/lookup-test/shebangscript
+
+$TEST_ROOT/lookup-test/shebangscript | grepQuiet "script works"
+
+# https://github.com/NixOS/nix/issues/5431
+mkdir $TEST_ROOT/marco{,/polo}
+echo 'abort "marco/shell.nix must not be used, but its mere existence used to cause #5431"' > $TEST_ROOT/marco/shell.nix
+cat >$TEST_ROOT/marco/polo/default.nix <<EOF
+#!/usr/bin/env nix-shell
+(import $TEST_ROOT/lookup-test/shell.nix {}).polo
+EOF
+chmod a+x $TEST_ROOT/marco/polo/default.nix
+(cd $TEST_ROOT/marco && ./polo/default.nix | grepQuiet "Polo")
+
+
+#####################
+# Flake equivalents #
+#####################
+
 # Test 'nix develop'.
 nix develop -f "$shellDotNix" shellDrv -c bash -c '[[ -n $stdenv ]]'
 
diff --git a/tests/functional/shell.nix b/tests/functional/shell.nix
index 6a7dd7ad1..75e3845ea 100644
--- a/tests/functional/shell.nix
+++ b/tests/functional/shell.nix
@@ -45,6 +45,17 @@ let pkgs = rec {
     TEST_inNixShell = if inNixShell then "true" else "false";
     inherit stdenv;
     outputs = ["dev" "out"];
+  } // {
+    shellHook = abort "Ignore non-drv shellHook attr";
+  };
+
+  # https://github.com/NixOS/nix/issues/5431
+  # See nix-shell.sh
+  polo = mkDerivation {
+    name = "polo";
+    shellHook = ''
+      echo Polo
+    '';
   };
 
   # Used by nix-shell -p

From afbe7c3d0890b530b69c09dd96411e51b11e130c Mon Sep 17 00:00:00 2001
From: Robert Hensing <robert@roberthensing.nl>
Date: Sat, 6 Jul 2024 23:15:01 +0200
Subject: [PATCH 11/25] rl-next: Enter PR

---
 doc/manual/rl-next/nix-shell-looks-for-shell-nix.md | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/doc/manual/rl-next/nix-shell-looks-for-shell-nix.md b/doc/manual/rl-next/nix-shell-looks-for-shell-nix.md
index 1f44ba33c..99be4148b 100644
--- a/doc/manual/rl-next/nix-shell-looks-for-shell-nix.md
+++ b/doc/manual/rl-next/nix-shell-looks-for-shell-nix.md
@@ -7,6 +7,8 @@ issues:
 - 4529
 - 5431
 - 11053
+prs:
+- 11057
 ---
 
 `nix-shell $x` now looks for `$x/shell.nix` when `$x` resolves to a directory.

From d5854f33e2872b583f00d35321405c022858b9ce Mon Sep 17 00:00:00 2001
From: Robert Hensing <robert@roberthensing.nl>
Date: Sun, 7 Jul 2024 00:18:26 +0200
Subject: [PATCH 12/25] rl-next: Typo

---
 doc/manual/rl-next/shebang-relative.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/doc/manual/rl-next/shebang-relative.md b/doc/manual/rl-next/shebang-relative.md
index dbda0db4c..e6ab9346f 100644
--- a/doc/manual/rl-next/shebang-relative.md
+++ b/doc/manual/rl-next/shebang-relative.md
@@ -3,6 +3,6 @@ prs: #5088
 description: {
 
 `nix-shell` shebangs use the script file's relative location to resolve relative paths to files passed as command line arguments, but expression arguments were still evaluated using the current working directory as a base path.
-The new behavior is that evalutations are performed relative to the script.
+The new behavior is that evaluations are performed relative to the script.
 
 }

From f5b59fbc6478ab944e75213e5ec711c0066ad43d Mon Sep 17 00:00:00 2001
From: Robert Hensing <robert@roberthensing.nl>
Date: Sun, 7 Jul 2024 00:22:21 +0200
Subject: [PATCH 13/25] Fix and extend nix-shell baseDir test

---
 src/libcmd/common-eval-args.cc      | 2 +-
 src/libutil/args/root.hh            | 1 +
 src/nix-build/nix-build.cc          | 6 ++++++
 tests/functional/nix-shell.sh       | 3 ++-
 tests/functional/shell.nix          | 1 +
 tests/functional/shell.shebang.expr | 9 +++++++++
 6 files changed, 20 insertions(+), 2 deletions(-)
 create mode 100755 tests/functional/shell.shebang.expr

diff --git a/src/libcmd/common-eval-args.cc b/src/libcmd/common-eval-args.cc
index 62745b681..ffc1ebd59 100644
--- a/src/libcmd/common-eval-args.cc
+++ b/src/libcmd/common-eval-args.cc
@@ -202,7 +202,7 @@ Bindings * MixEvalArgs::getAutoArgs(EvalState & state)
         auto v = state.allocValue();
         std::visit(overloaded {
             [&](const AutoArgExpr & arg) {
-                state.mkThunk_(*v, state.parseExprFromString(arg.expr, state.rootPath(".")));
+                state.mkThunk_(*v, state.parseExprFromString(arg.expr, true ? state.rootPath(absPath(getCommandBaseDir())) : state.rootPath(".")));
             },
             [&](const AutoArgString & arg) {
                 v->mkString(arg.s);
diff --git a/src/libutil/args/root.hh b/src/libutil/args/root.hh
index 5c55c37a5..34a43b538 100644
--- a/src/libutil/args/root.hh
+++ b/src/libutil/args/root.hh
@@ -29,6 +29,7 @@ struct Completions final : AddCompletions
  */
 class RootArgs : virtual public Args
 {
+protected:
     /**
      * @brief The command's "working directory", but only set when top level.
      *
diff --git a/src/nix-build/nix-build.cc b/src/nix-build/nix-build.cc
index 872295045..cfe183888 100644
--- a/src/nix-build/nix-build.cc
+++ b/src/nix-build/nix-build.cc
@@ -183,6 +183,9 @@ static void main_nix_build(int argc, char * * argv)
     struct MyArgs : LegacyArgs, MixEvalArgs
     {
         using LegacyArgs::LegacyArgs;
+        void setBaseDir(Path baseDir) {
+            commandBaseDir = baseDir;
+        }
     };
 
     MyArgs myArgs(myName, [&](Strings::iterator & arg, const Strings::iterator & end) {
@@ -290,6 +293,9 @@ static void main_nix_build(int argc, char * * argv)
     state->repair = myArgs.repair;
     if (myArgs.repair) buildMode = bmRepair;
 
+    if (inShebang) {
+        myArgs.setBaseDir(absPath(dirOf(script)));
+    }
     auto autoArgs = myArgs.getAutoArgs(*state);
 
     auto autoArgsWithInNixShell = autoArgs;
diff --git a/tests/functional/nix-shell.sh b/tests/functional/nix-shell.sh
index f881acd03..596ac5951 100755
--- a/tests/functional/nix-shell.sh
+++ b/tests/functional/nix-shell.sh
@@ -72,8 +72,9 @@ chmod a+rx $TEST_ROOT/shell.shebang.expr
 ! $TEST_ROOT/shell.shebang.expr bar
 cp shell.nix config.nix $TEST_ROOT
 # Should succeed
+echo "cwd: $PWD"
 output=$($TEST_ROOT/shell.shebang.expr bar)
-[ "$output" = '-e load(ARGV.shift) -- '"$TEST_ROOT"'/shell.shebang.expr bar' ]
+[ "$output" = foo ]
 
 # Test nix-shell shebang mode again with metacharacters in the filename.
 # First word of filename is chosen to not match any file in the test root.
diff --git a/tests/functional/shell.nix b/tests/functional/shell.nix
index 75e3845ea..a7577ff63 100644
--- a/tests/functional/shell.nix
+++ b/tests/functional/shell.nix
@@ -43,6 +43,7 @@ let pkgs = rec {
     ASCII_PERCENT = "%";
     ASCII_AT = "@";
     TEST_inNixShell = if inNixShell then "true" else "false";
+    FOO = fooContents;
     inherit stdenv;
     outputs = ["dev" "out"];
   } // {
diff --git a/tests/functional/shell.shebang.expr b/tests/functional/shell.shebang.expr
new file mode 100755
index 000000000..c602dedbf
--- /dev/null
+++ b/tests/functional/shell.shebang.expr
@@ -0,0 +1,9 @@
+#! @ENV_PROG@ nix-shell
+#! nix-shell "{ script, path, ... }: assert path == ./shell.nix; script { }"
+#! nix-shell --no-substitute
+#! nix-shell --expr 
+#! nix-shell --arg script "import ./shell.nix"
+#! nix-shell --arg path "./shell.nix"
+#! nix-shell -A shellDrv
+#! nix-shell -i bash
+echo "$FOO"

From 6c6d5263e26bc463aee97e49a5e9b8d867a4731a Mon Sep 17 00:00:00 2001
From: Robert Hensing <robert@roberthensing.nl>
Date: Sat, 6 Jul 2024 22:58:15 +0200
Subject: [PATCH 14/25] Add legacy setting:
 nix-shell-always-looks-for-shell-nix

---
 src/libcmd/common-eval-args.cc       |  7 +++++++
 src/libcmd/common-eval-args.hh       |  6 ++++++
 src/libcmd/compatibility-settings.hh | 19 +++++++++++++++++++
 src/libcmd/meson.build               |  1 +
 src/nix-build/nix-build.cc           | 23 ++++++++++++++++++-----
 tests/functional/nix-shell.sh        |  9 +++++++++
 6 files changed, 60 insertions(+), 5 deletions(-)
 create mode 100644 src/libcmd/compatibility-settings.hh

diff --git a/src/libcmd/common-eval-args.cc b/src/libcmd/common-eval-args.cc
index 01546f9a0..62745b681 100644
--- a/src/libcmd/common-eval-args.cc
+++ b/src/libcmd/common-eval-args.cc
@@ -11,6 +11,8 @@
 #include "command.hh"
 #include "tarball.hh"
 #include "fetch-to-store.hh"
+#include "compatibility-settings.hh"
+#include "eval-settings.hh"
 
 namespace nix {
 
@@ -33,6 +35,11 @@ EvalSettings evalSettings {
 
 static GlobalConfig::Register rEvalSettings(&evalSettings);
 
+CompatibilitySettings compatibilitySettings {};
+
+static GlobalConfig::Register rCompatibilitySettings(&compatibilitySettings);
+
+
 MixEvalArgs::MixEvalArgs()
 {
     addFlag({
diff --git a/src/libcmd/common-eval-args.hh b/src/libcmd/common-eval-args.hh
index 189abf0ed..8d303ee7c 100644
--- a/src/libcmd/common-eval-args.hh
+++ b/src/libcmd/common-eval-args.hh
@@ -13,6 +13,7 @@ namespace nix {
 class Store;
 class EvalState;
 struct EvalSettings;
+struct CompatibilitySettings;
 class Bindings;
 struct SourcePath;
 
@@ -21,6 +22,11 @@ struct SourcePath;
  */
 extern EvalSettings evalSettings;
 
+/**
+ * Settings that control behaviors that have changed since Nix 2.3.
+ */
+extern CompatibilitySettings compatibilitySettings;
+
 struct MixEvalArgs : virtual Args, virtual MixRepair
 {
     static constexpr auto category = "Common evaluation options";
diff --git a/src/libcmd/compatibility-settings.hh b/src/libcmd/compatibility-settings.hh
new file mode 100644
index 000000000..5dc0eaf2b
--- /dev/null
+++ b/src/libcmd/compatibility-settings.hh
@@ -0,0 +1,19 @@
+#pragma once
+#include "config.hh"
+
+namespace nix {
+struct CompatibilitySettings : public Config
+{
+
+    CompatibilitySettings() = default;
+
+    Setting<bool> nixShellAlwaysLooksForShellNix{this, true, "nix-shell-always-looks-for-shell-nix", R"(
+        Before Nix 2.24, [`nix-shell`](@docroot@/command-ref/nix-shell.md) would only look at `shell.nix` if it was in the working directory - when no file was specified.
+
+        Since Nix 2.24, `nix-shell` always looks for a `shell.nix`, whether that's in the working directory, or in a directory that was passed as an argument.
+
+        You may set this to `false` to revert to the Nix 2.3 behavior.
+    )"};
+};
+
+};
diff --git a/src/libcmd/meson.build b/src/libcmd/meson.build
index d9a90508a..2c8a9fa33 100644
--- a/src/libcmd/meson.build
+++ b/src/libcmd/meson.build
@@ -97,6 +97,7 @@ headers = [config_h] + files(
   'command-installable-value.hh',
   'command.hh',
   'common-eval-args.hh',
+  'compatibility-settings.hh',
   'editor-for.hh',
   'installable-attr-path.hh',
   'installable-derived-path.hh',
diff --git a/src/nix-build/nix-build.cc b/src/nix-build/nix-build.cc
index 30cc86456..d37b16bdc 100644
--- a/src/nix-build/nix-build.cc
+++ b/src/nix-build/nix-build.cc
@@ -26,6 +26,7 @@
 #include "legacy.hh"
 #include "users.hh"
 #include "network-proxy.hh"
+#include "compatibility-settings.hh"
 
 using namespace nix;
 using namespace std::string_literals;
@@ -100,7 +101,13 @@ static SourcePath resolveShellExprPath(SourcePath path)
     auto resolvedOrDir = resolveExprPath(path, false);
     if (resolvedOrDir.resolveSymlinks().lstat().type == SourceAccessor::tDirectory) {
         if ((resolvedOrDir / "shell.nix").pathExists()) {
-            return resolvedOrDir / "shell.nix";
+            if (compatibilitySettings.nixShellAlwaysLooksForShellNix) {
+                return resolvedOrDir / "shell.nix";
+            } else {
+                warn("Skipping '%1%', because the setting '%2%' is disabled. This is a deprecated behavior. Consider enabling '%2%'.",
+                    resolvedOrDir / "shell.nix",
+                    "nix-shell-always-looks-for-shell-nix");
+            }
         }
         if ((resolvedOrDir / "default.nix").pathExists()) {
             return resolvedOrDir / "default.nix";
@@ -302,11 +309,17 @@ static void main_nix_build(int argc, char * * argv)
         fromArgs = true;
         remainingArgs = {joined.str()};
     } else if (!fromArgs && remainingArgs.empty()) {
-        remainingArgs = {"."};
+        if (isNixShell && !compatibilitySettings.nixShellAlwaysLooksForShellNix && std::filesystem::exists("shell.nix")) {
+            // If we're in 2.3 compatibility mode, we need to look for shell.nix
+            // now, because it won't be done later.
+            remainingArgs = {"shell.nix"};
+        } else {
+            remainingArgs = {"."};
 
-        // Instead of letting it throw later, we throw here to give a more relevant error message
-        if (isNixShell && !std::filesystem::exists("shell.nix") && !std::filesystem::exists("default.nix"))
-            throw Error("no argument specified and no '%s' or '%s' file found in the working directory", "shell.nix", "default.nix");
+            // Instead of letting it throw later, we throw here to give a more relevant error message
+            if (isNixShell && !std::filesystem::exists("shell.nix") && !std::filesystem::exists("default.nix"))
+                throw Error("no argument specified and no '%s' or '%s' file found in the working directory", "shell.nix", "default.nix");
+        }
     }
 
     if (isNixShell)
diff --git a/tests/functional/nix-shell.sh b/tests/functional/nix-shell.sh
index b7a7db27c..2a1d556dd 100755
--- a/tests/functional/nix-shell.sh
+++ b/tests/functional/nix-shell.sh
@@ -21,6 +21,10 @@ output=$(nix-shell --pure "$shellDotNix" -A shellDrv --run \
 
 [ "$output" = " - foo - bar - true" ]
 
+output=$(nix-shell --pure "$shellDotNix" -A shellDrv --option nix-shell-always-looks-for-shell-nix false --run \
+    'echo "$IMPURE_VAR - $VAR_FROM_STDENV_SETUP - $VAR_FROM_NIX - $TEST_inNixShell"')
+[ "$output" = " - foo - bar - true" ]
+
 # Test --keep
 output=$(nix-shell --pure --keep SELECTED_IMPURE_VAR "$shellDotNix" -A shellDrv --run \
     'echo "$IMPURE_VAR - $VAR_FROM_STDENV_SETUP - $VAR_FROM_NIX - $SELECTED_IMPURE_VAR"')
@@ -101,6 +105,11 @@ nix-shell $TEST_ROOT/lookup-test -A shellDrv --run 'echo "it works"' | grepQuiet
 # https://github.com/NixOS/nix/issues/4529
 nix-shell -I "testRoot=$TEST_ROOT" '<testRoot/lookup-test>' -A shellDrv --run 'echo "it works"' | grepQuiet "it works"
 
+expectStderr 1 nix-shell $TEST_ROOT/lookup-test -A shellDrv --run 'echo "it works"' --option nix-shell-always-looks-for-shell-nix false \
+  | grepQuiet -F "do not load default.nix!" # we did, because we chose to enable legacy behavior
+expectStderr 1 nix-shell $TEST_ROOT/lookup-test -A shellDrv --run 'echo "it works"' --option nix-shell-always-looks-for-shell-nix false \
+  | grepQuiet "Skipping .*lookup-test/shell\.nix.*, because the setting .*nix-shell-always-looks-for-shell-nix.* is disabled. This is a deprecated behavior\. Consider enabling .*nix-shell-always-looks-for-shell-nix.*"
+
 (
   cd $TEST_ROOT/empty;
   expectStderr 1 nix-shell | \

From 6959ac157bf4e9ff8cbd30033cf8de07f5849ab7 Mon Sep 17 00:00:00 2001
From: Robert Hensing <robert@roberthensing.nl>
Date: Sat, 6 Jul 2024 23:02:32 +0200
Subject: [PATCH 15/25] rl-next: Add note about shell.nix lookups

---
 .../rl-next/nix-shell-looks-for-shell-nix.md  | 28 +++++++++++++++++++
 1 file changed, 28 insertions(+)
 create mode 100644 doc/manual/rl-next/nix-shell-looks-for-shell-nix.md

diff --git a/doc/manual/rl-next/nix-shell-looks-for-shell-nix.md b/doc/manual/rl-next/nix-shell-looks-for-shell-nix.md
new file mode 100644
index 000000000..99be4148b
--- /dev/null
+++ b/doc/manual/rl-next/nix-shell-looks-for-shell-nix.md
@@ -0,0 +1,28 @@
+---
+synopsis: "`nix-shell <directory>` looks for `shell.nix`"
+significance: significant
+issues:
+- 496
+- 2279
+- 4529
+- 5431
+- 11053
+prs:
+- 11057
+---
+
+`nix-shell $x` now looks for `$x/shell.nix` when `$x` resolves to a directory.
+
+Although this might be seen as a breaking change, its primarily interactive usage makes it a minor issue.
+This adjustment addresses a commonly reported problem.
+
+This also applies to `nix-shell` shebang scripts. Consider the following example:
+
+```shell
+#!/usr/bin/env nix-shell
+#!nix-shell -i bash
+```
+
+This will now load `shell.nix` from the script's directory, if it exists; `default.nix` otherwise.
+
+The old behavior can be opted into by setting the option [`nix-shell-always-looks-for-shell-nix`](@docroot@/command-ref/conf-file.md#conf-nix-shell-always-looks-for-shell-nix) to `false`.

From 63262e78c7fd281b813e858640adbaa6f6b3d826 Mon Sep 17 00:00:00 2001
From: Robert Hensing <robert@roberthensing.nl>
Date: Sun, 7 Jul 2024 00:55:33 +0200
Subject: [PATCH 16/25] Add opt-out:
 nix-shell-shebang-arguments-relative-to-script

---
 doc/manual/rl-next/shebang-relative.md | 2 ++
 src/libcmd/common-eval-args.cc         | 2 +-
 src/libcmd/compatibility-settings.hh   | 9 +++++++++
 src/nix-build/nix-build.cc             | 4 ++--
 tests/functional/nix-shell.sh          | 8 ++++++++
 5 files changed, 22 insertions(+), 3 deletions(-)

diff --git a/doc/manual/rl-next/shebang-relative.md b/doc/manual/rl-next/shebang-relative.md
index e6ab9346f..ab39a359c 100644
--- a/doc/manual/rl-next/shebang-relative.md
+++ b/doc/manual/rl-next/shebang-relative.md
@@ -5,4 +5,6 @@ description: {
 `nix-shell` shebangs use the script file's relative location to resolve relative paths to files passed as command line arguments, but expression arguments were still evaluated using the current working directory as a base path.
 The new behavior is that evaluations are performed relative to the script.
 
+The old behavior can be opted into by setting the option [`nix-shell-shebang-arguments-relative-to-script`](@docroot@/command-ref/conf-file.md#conf-nix-shell-shebang-arguments-relative-to-script) to `false`.
+
 }
diff --git a/src/libcmd/common-eval-args.cc b/src/libcmd/common-eval-args.cc
index ffc1ebd59..a243b8c49 100644
--- a/src/libcmd/common-eval-args.cc
+++ b/src/libcmd/common-eval-args.cc
@@ -202,7 +202,7 @@ Bindings * MixEvalArgs::getAutoArgs(EvalState & state)
         auto v = state.allocValue();
         std::visit(overloaded {
             [&](const AutoArgExpr & arg) {
-                state.mkThunk_(*v, state.parseExprFromString(arg.expr, true ? state.rootPath(absPath(getCommandBaseDir())) : state.rootPath(".")));
+                state.mkThunk_(*v, state.parseExprFromString(arg.expr, compatibilitySettings.nixShellShebangArgumentsRelativeToScript ? state.rootPath(absPath(getCommandBaseDir())) : state.rootPath(".")));
             },
             [&](const AutoArgString & arg) {
                 v->mkString(arg.s);
diff --git a/src/libcmd/compatibility-settings.hh b/src/libcmd/compatibility-settings.hh
index 5dc0eaf2b..961001080 100644
--- a/src/libcmd/compatibility-settings.hh
+++ b/src/libcmd/compatibility-settings.hh
@@ -14,6 +14,15 @@ struct CompatibilitySettings : public Config
 
         You may set this to `false` to revert to the Nix 2.3 behavior.
     )"};
+
+    Setting<bool> nixShellShebangArgumentsRelativeToScript{
+        this, true, "nix-shell-shebang-arguments-relative-to-script", R"(
+        Before Nix 2.24, the arguments in a `nix-shell` shebang - as well as `--arg` - were relative to working directory.
+
+        Since Nix 2.24, the arguments are relative to the [base directory](@docroot@/glossary.md#gloss-base-directory) defined as the script's directory.
+
+        You may set this to `false` to revert to the Nix 2.3 behavior.
+    )"};
 };
 
 };
diff --git a/src/nix-build/nix-build.cc b/src/nix-build/nix-build.cc
index cfe183888..f4af3fd04 100644
--- a/src/nix-build/nix-build.cc
+++ b/src/nix-build/nix-build.cc
@@ -293,7 +293,7 @@ static void main_nix_build(int argc, char * * argv)
     state->repair = myArgs.repair;
     if (myArgs.repair) buildMode = bmRepair;
 
-    if (inShebang) {
+    if (inShebang && compatibilitySettings.nixShellShebangArgumentsRelativeToScript) {
         myArgs.setBaseDir(absPath(dirOf(script)));
     }
     auto autoArgs = myArgs.getAutoArgs(*state);
@@ -345,7 +345,7 @@ static void main_nix_build(int argc, char * * argv)
             if (fromArgs)
                 exprs.push_back(state->parseExprFromString(
                     std::move(i),
-                    inShebang ? lookupFileArg(*state, baseDir) : state->rootPath(".")
+                    (inShebang && compatibilitySettings.nixShellShebangArgumentsRelativeToScript) ? lookupFileArg(*state, baseDir) : state->rootPath(".")
                 ));
             else {
                 auto absolute = i;
diff --git a/tests/functional/nix-shell.sh b/tests/functional/nix-shell.sh
index 596ac5951..fd3edf81a 100755
--- a/tests/functional/nix-shell.sh
+++ b/tests/functional/nix-shell.sh
@@ -76,6 +76,14 @@ echo "cwd: $PWD"
 output=$($TEST_ROOT/shell.shebang.expr bar)
 [ "$output" = foo ]
 
+# Test nix-shell shebang mode with an alternate working directory
+sed -e "s|@ENV_PROG@|$(type -P env)|" shell.shebang.legacy.expr > $TEST_ROOT/shell.shebang.legacy.expr
+chmod a+rx $TEST_ROOT/shell.shebang.legacy.expr
+# Should fail due to expressions using relative path
+mkdir -p "$TEST_ROOT/somewhere-unrelated"
+output="$(cd "$TEST_ROOT/somewhere-unrelated"; $TEST_ROOT/shell.shebang.legacy.expr bar;)"
+[[ $(realpath "$output") = $(realpath "$TEST_ROOT/somewhere-unrelated") ]]
+
 # Test nix-shell shebang mode again with metacharacters in the filename.
 # First word of filename is chosen to not match any file in the test root.
 sed -e "s|@ENV_PROG@|$(type -P env)|" shell.shebang.sh > $TEST_ROOT/spaced\ \\\'\"shell.shebang.sh

From 73602a7c6f4dc6f4f4bea8368a8564403b7b5604 Mon Sep 17 00:00:00 2001
From: Robert Hensing <robert@roberthensing.nl>
Date: Sat, 6 Jul 2024 21:31:24 +0200
Subject: [PATCH 17/25] nix-shell: Look for shell.nix when directory is
 specified

---
 src/libexpr/eval.cc           |  4 ++--
 src/libexpr/eval.hh           |  4 +++-
 src/nix-build/nix-build.cc    | 34 ++++++++++++++++++++++-----
 tests/functional/nix-shell.sh | 44 +++++++++++++++++++++++++++++++++++
 tests/functional/shell.nix    | 11 +++++++++
 5 files changed, 88 insertions(+), 9 deletions(-)

diff --git a/src/libexpr/eval.cc b/src/libexpr/eval.cc
index 48ed66883..2a0862123 100644
--- a/src/libexpr/eval.cc
+++ b/src/libexpr/eval.cc
@@ -2650,7 +2650,7 @@ void EvalState::printStatistics()
 }
 
 
-SourcePath resolveExprPath(SourcePath path)
+SourcePath resolveExprPath(SourcePath path, bool addDefaultNix)
 {
     unsigned int followCount = 0, maxFollow = 1024;
 
@@ -2666,7 +2666,7 @@ SourcePath resolveExprPath(SourcePath path)
     }
 
     /* If `path' refers to a directory, append `/default.nix'. */
-    if (path.resolveSymlinks().lstat().type == SourceAccessor::tDirectory)
+    if (addDefaultNix && path.resolveSymlinks().lstat().type == SourceAccessor::tDirectory)
         return path / "default.nix";
 
     return path;
diff --git a/src/libexpr/eval.hh b/src/libexpr/eval.hh
index b84bc9907..e45358055 100644
--- a/src/libexpr/eval.hh
+++ b/src/libexpr/eval.hh
@@ -850,8 +850,10 @@ std::string showType(const Value & v);
 
 /**
  * If `path` refers to a directory, then append "/default.nix".
+ *
+ * @param addDefaultNix Whether to append "/default.nix" after resolving symlinks.
  */
-SourcePath resolveExprPath(SourcePath path);
+SourcePath resolveExprPath(SourcePath path, bool addDefaultNix = true);
 
 /**
  * Whether a URI is allowed, assuming restrictEval is enabled
diff --git a/src/nix-build/nix-build.cc b/src/nix-build/nix-build.cc
index e873f712b..30cc86456 100644
--- a/src/nix-build/nix-build.cc
+++ b/src/nix-build/nix-build.cc
@@ -90,6 +90,26 @@ static std::vector<std::string> shellwords(const std::string & s)
     return res;
 }
 
+/**
+ * Like `resolveExprPath`, but prefers `shell.nix` instead of `default.nix`,
+ * and if `path` was a directory, it checks eagerly whether `shell.nix` or
+ * `default.nix` exist, throwing an error if they don't.
+ */
+static SourcePath resolveShellExprPath(SourcePath path)
+{
+    auto resolvedOrDir = resolveExprPath(path, false);
+    if (resolvedOrDir.resolveSymlinks().lstat().type == SourceAccessor::tDirectory) {
+        if ((resolvedOrDir / "shell.nix").pathExists()) {
+            return resolvedOrDir / "shell.nix";
+        }
+        if ((resolvedOrDir / "default.nix").pathExists()) {
+            return resolvedOrDir / "default.nix";
+        }
+        throw Error("neither '%s' nor '%s' found in '%s'", "shell.nix", "default.nix", resolvedOrDir);
+    }
+    return resolvedOrDir;
+}
+
 static void main_nix_build(int argc, char * * argv)
 {
     auto dryRun = false;
@@ -281,11 +301,12 @@ static void main_nix_build(int argc, char * * argv)
         joined << "]; } \"\"";
         fromArgs = true;
         remainingArgs = {joined.str()};
-    } else if (!fromArgs) {
-        if (remainingArgs.empty() && isNixShell && pathExists("shell.nix"))
-            remainingArgs = {"shell.nix"};
-        if (remainingArgs.empty())
-            remainingArgs = {"default.nix"};
+    } else if (!fromArgs && remainingArgs.empty()) {
+        remainingArgs = {"."};
+
+        // Instead of letting it throw later, we throw here to give a more relevant error message
+        if (isNixShell && !std::filesystem::exists("shell.nix") && !std::filesystem::exists("default.nix"))
+            throw Error("no argument specified and no '%s' or '%s' file found in the working directory", "shell.nix", "default.nix");
     }
 
     if (isNixShell)
@@ -317,7 +338,8 @@ static void main_nix_build(int argc, char * * argv)
 
                     auto sourcePath = lookupFileArg(*state,
                                     baseDir);
-                    auto resolvedPath = resolveExprPath(sourcePath);
+                    auto resolvedPath =
+                        isNixShell ? resolveShellExprPath(sourcePath) : resolveExprPath(sourcePath);
 
                     exprs.push_back(state->parseExprFromFile(resolvedPath));
                 }
diff --git a/tests/functional/nix-shell.sh b/tests/functional/nix-shell.sh
index 2c94705de..f54e3621c 100755
--- a/tests/functional/nix-shell.sh
+++ b/tests/functional/nix-shell.sh
@@ -91,6 +91,50 @@ sed -e "s|@ENV_PROG@|$(type -P env)|" shell.shebang.nix > $TEST_ROOT/shell.sheba
 chmod a+rx $TEST_ROOT/shell.shebang.nix
 $TEST_ROOT/shell.shebang.nix
 
+mkdir $TEST_ROOT/lookup-test $TEST_ROOT/empty
+
+echo "import $shellDotNix" > $TEST_ROOT/lookup-test/shell.nix
+cp config.nix $TEST_ROOT/lookup-test/
+echo 'abort "do not load default.nix!"' > $TEST_ROOT/lookup-test/default.nix
+
+nix-shell $TEST_ROOT/lookup-test -A shellDrv --run 'echo "it works"' | grepQuiet "it works"
+# https://github.com/NixOS/nix/issues/4529
+nix-shell -I "testRoot=$TEST_ROOT" '<testRoot/lookup-test>' -A shellDrv --run 'echo "it works"' | grepQuiet "it works"
+
+(
+  cd $TEST_ROOT/empty;
+  expectStderr 1 nix-shell | \
+    grepQuiet "error.*no argument specified and no .*shell\.nix.* or .*default\.nix.* file found in the working directory"
+)
+
+expectStderr 1 nix-shell -I "testRoot=$TEST_ROOT" '<testRoot/empty>' |
+  grepQuiet "error.*neither .*shell\.nix.* nor .*default\.nix.* found in .*/empty"
+
+cat >$TEST_ROOT/lookup-test/shebangscript <<EOF
+#!$(type -P env) nix-shell
+#!nix-shell -A shellDrv -i bash
+[[ \$VAR_FROM_NIX == bar ]]
+echo "script works"
+EOF
+chmod +x $TEST_ROOT/lookup-test/shebangscript
+
+$TEST_ROOT/lookup-test/shebangscript | grepQuiet "script works"
+
+# https://github.com/NixOS/nix/issues/5431
+mkdir $TEST_ROOT/marco{,/polo}
+echo 'abort "marco/shell.nix must not be used, but its mere existence used to cause #5431"' > $TEST_ROOT/marco/shell.nix
+cat >$TEST_ROOT/marco/polo/default.nix <<EOF
+#!$(type -P env) nix-shell
+(import $TEST_ROOT/lookup-test/shell.nix {}).polo
+EOF
+chmod a+x $TEST_ROOT/marco/polo/default.nix
+(cd $TEST_ROOT/marco && ./polo/default.nix | grepQuiet "Polo")
+
+
+#####################
+# Flake equivalents #
+#####################
+
 # Test 'nix develop'.
 nix develop -f "$shellDotNix" shellDrv -c bash -c '[[ -n $stdenv ]]'
 
diff --git a/tests/functional/shell.nix b/tests/functional/shell.nix
index 6a7dd7ad1..75e3845ea 100644
--- a/tests/functional/shell.nix
+++ b/tests/functional/shell.nix
@@ -45,6 +45,17 @@ let pkgs = rec {
     TEST_inNixShell = if inNixShell then "true" else "false";
     inherit stdenv;
     outputs = ["dev" "out"];
+  } // {
+    shellHook = abort "Ignore non-drv shellHook attr";
+  };
+
+  # https://github.com/NixOS/nix/issues/5431
+  # See nix-shell.sh
+  polo = mkDerivation {
+    name = "polo";
+    shellHook = ''
+      echo Polo
+    '';
   };
 
   # Used by nix-shell -p

From 2f1fada76b6d29ad880b358b20860ecedc1ea53f Mon Sep 17 00:00:00 2001
From: Robert Hensing <robert@roberthensing.nl>
Date: Sat, 6 Jul 2024 22:58:15 +0200
Subject: [PATCH 18/25] Add legacy setting:
 nix-shell-always-looks-for-shell-nix

---
 src/libcmd/common-eval-args.cc       |  7 +++++++
 src/libcmd/common-eval-args.hh       |  6 ++++++
 src/libcmd/compatibility-settings.hh | 19 +++++++++++++++++++
 src/libcmd/meson.build               |  1 +
 src/nix-build/nix-build.cc           | 23 ++++++++++++++++++-----
 tests/functional/nix-shell.sh        |  9 +++++++++
 6 files changed, 60 insertions(+), 5 deletions(-)
 create mode 100644 src/libcmd/compatibility-settings.hh

diff --git a/src/libcmd/common-eval-args.cc b/src/libcmd/common-eval-args.cc
index 01546f9a0..62745b681 100644
--- a/src/libcmd/common-eval-args.cc
+++ b/src/libcmd/common-eval-args.cc
@@ -11,6 +11,8 @@
 #include "command.hh"
 #include "tarball.hh"
 #include "fetch-to-store.hh"
+#include "compatibility-settings.hh"
+#include "eval-settings.hh"
 
 namespace nix {
 
@@ -33,6 +35,11 @@ EvalSettings evalSettings {
 
 static GlobalConfig::Register rEvalSettings(&evalSettings);
 
+CompatibilitySettings compatibilitySettings {};
+
+static GlobalConfig::Register rCompatibilitySettings(&compatibilitySettings);
+
+
 MixEvalArgs::MixEvalArgs()
 {
     addFlag({
diff --git a/src/libcmd/common-eval-args.hh b/src/libcmd/common-eval-args.hh
index 189abf0ed..8d303ee7c 100644
--- a/src/libcmd/common-eval-args.hh
+++ b/src/libcmd/common-eval-args.hh
@@ -13,6 +13,7 @@ namespace nix {
 class Store;
 class EvalState;
 struct EvalSettings;
+struct CompatibilitySettings;
 class Bindings;
 struct SourcePath;
 
@@ -21,6 +22,11 @@ struct SourcePath;
  */
 extern EvalSettings evalSettings;
 
+/**
+ * Settings that control behaviors that have changed since Nix 2.3.
+ */
+extern CompatibilitySettings compatibilitySettings;
+
 struct MixEvalArgs : virtual Args, virtual MixRepair
 {
     static constexpr auto category = "Common evaluation options";
diff --git a/src/libcmd/compatibility-settings.hh b/src/libcmd/compatibility-settings.hh
new file mode 100644
index 000000000..5dc0eaf2b
--- /dev/null
+++ b/src/libcmd/compatibility-settings.hh
@@ -0,0 +1,19 @@
+#pragma once
+#include "config.hh"
+
+namespace nix {
+struct CompatibilitySettings : public Config
+{
+
+    CompatibilitySettings() = default;
+
+    Setting<bool> nixShellAlwaysLooksForShellNix{this, true, "nix-shell-always-looks-for-shell-nix", R"(
+        Before Nix 2.24, [`nix-shell`](@docroot@/command-ref/nix-shell.md) would only look at `shell.nix` if it was in the working directory - when no file was specified.
+
+        Since Nix 2.24, `nix-shell` always looks for a `shell.nix`, whether that's in the working directory, or in a directory that was passed as an argument.
+
+        You may set this to `false` to revert to the Nix 2.3 behavior.
+    )"};
+};
+
+};
diff --git a/src/libcmd/meson.build b/src/libcmd/meson.build
index d9a90508a..2c8a9fa33 100644
--- a/src/libcmd/meson.build
+++ b/src/libcmd/meson.build
@@ -97,6 +97,7 @@ headers = [config_h] + files(
   'command-installable-value.hh',
   'command.hh',
   'common-eval-args.hh',
+  'compatibility-settings.hh',
   'editor-for.hh',
   'installable-attr-path.hh',
   'installable-derived-path.hh',
diff --git a/src/nix-build/nix-build.cc b/src/nix-build/nix-build.cc
index 30cc86456..d37b16bdc 100644
--- a/src/nix-build/nix-build.cc
+++ b/src/nix-build/nix-build.cc
@@ -26,6 +26,7 @@
 #include "legacy.hh"
 #include "users.hh"
 #include "network-proxy.hh"
+#include "compatibility-settings.hh"
 
 using namespace nix;
 using namespace std::string_literals;
@@ -100,7 +101,13 @@ static SourcePath resolveShellExprPath(SourcePath path)
     auto resolvedOrDir = resolveExprPath(path, false);
     if (resolvedOrDir.resolveSymlinks().lstat().type == SourceAccessor::tDirectory) {
         if ((resolvedOrDir / "shell.nix").pathExists()) {
-            return resolvedOrDir / "shell.nix";
+            if (compatibilitySettings.nixShellAlwaysLooksForShellNix) {
+                return resolvedOrDir / "shell.nix";
+            } else {
+                warn("Skipping '%1%', because the setting '%2%' is disabled. This is a deprecated behavior. Consider enabling '%2%'.",
+                    resolvedOrDir / "shell.nix",
+                    "nix-shell-always-looks-for-shell-nix");
+            }
         }
         if ((resolvedOrDir / "default.nix").pathExists()) {
             return resolvedOrDir / "default.nix";
@@ -302,11 +309,17 @@ static void main_nix_build(int argc, char * * argv)
         fromArgs = true;
         remainingArgs = {joined.str()};
     } else if (!fromArgs && remainingArgs.empty()) {
-        remainingArgs = {"."};
+        if (isNixShell && !compatibilitySettings.nixShellAlwaysLooksForShellNix && std::filesystem::exists("shell.nix")) {
+            // If we're in 2.3 compatibility mode, we need to look for shell.nix
+            // now, because it won't be done later.
+            remainingArgs = {"shell.nix"};
+        } else {
+            remainingArgs = {"."};
 
-        // Instead of letting it throw later, we throw here to give a more relevant error message
-        if (isNixShell && !std::filesystem::exists("shell.nix") && !std::filesystem::exists("default.nix"))
-            throw Error("no argument specified and no '%s' or '%s' file found in the working directory", "shell.nix", "default.nix");
+            // Instead of letting it throw later, we throw here to give a more relevant error message
+            if (isNixShell && !std::filesystem::exists("shell.nix") && !std::filesystem::exists("default.nix"))
+                throw Error("no argument specified and no '%s' or '%s' file found in the working directory", "shell.nix", "default.nix");
+        }
     }
 
     if (isNixShell)
diff --git a/tests/functional/nix-shell.sh b/tests/functional/nix-shell.sh
index f54e3621c..65ff279f8 100755
--- a/tests/functional/nix-shell.sh
+++ b/tests/functional/nix-shell.sh
@@ -21,6 +21,10 @@ output=$(nix-shell --pure "$shellDotNix" -A shellDrv --run \
 
 [ "$output" = " - foo - bar - true" ]
 
+output=$(nix-shell --pure "$shellDotNix" -A shellDrv --option nix-shell-always-looks-for-shell-nix false --run \
+    'echo "$IMPURE_VAR - $VAR_FROM_STDENV_SETUP - $VAR_FROM_NIX - $TEST_inNixShell"')
+[ "$output" = " - foo - bar - true" ]
+
 # Test --keep
 output=$(nix-shell --pure --keep SELECTED_IMPURE_VAR "$shellDotNix" -A shellDrv --run \
     'echo "$IMPURE_VAR - $VAR_FROM_STDENV_SETUP - $VAR_FROM_NIX - $SELECTED_IMPURE_VAR"')
@@ -101,6 +105,11 @@ nix-shell $TEST_ROOT/lookup-test -A shellDrv --run 'echo "it works"' | grepQuiet
 # https://github.com/NixOS/nix/issues/4529
 nix-shell -I "testRoot=$TEST_ROOT" '<testRoot/lookup-test>' -A shellDrv --run 'echo "it works"' | grepQuiet "it works"
 
+expectStderr 1 nix-shell $TEST_ROOT/lookup-test -A shellDrv --run 'echo "it works"' --option nix-shell-always-looks-for-shell-nix false \
+  | grepQuiet -F "do not load default.nix!" # we did, because we chose to enable legacy behavior
+expectStderr 1 nix-shell $TEST_ROOT/lookup-test -A shellDrv --run 'echo "it works"' --option nix-shell-always-looks-for-shell-nix false \
+  | grepQuiet "Skipping .*lookup-test/shell\.nix.*, because the setting .*nix-shell-always-looks-for-shell-nix.* is disabled. This is a deprecated behavior\. Consider enabling .*nix-shell-always-looks-for-shell-nix.*"
+
 (
   cd $TEST_ROOT/empty;
   expectStderr 1 nix-shell | \

From c4a20a41019ef3cd806059102cbe1d45fcbdd2b8 Mon Sep 17 00:00:00 2001
From: Robert Hensing <robert@roberthensing.nl>
Date: Sat, 6 Jul 2024 23:02:32 +0200
Subject: [PATCH 19/25] rl-next: Add note about shell.nix lookups

---
 .../rl-next/nix-shell-looks-for-shell-nix.md  | 28 +++++++++++++++++++
 1 file changed, 28 insertions(+)
 create mode 100644 doc/manual/rl-next/nix-shell-looks-for-shell-nix.md

diff --git a/doc/manual/rl-next/nix-shell-looks-for-shell-nix.md b/doc/manual/rl-next/nix-shell-looks-for-shell-nix.md
new file mode 100644
index 000000000..99be4148b
--- /dev/null
+++ b/doc/manual/rl-next/nix-shell-looks-for-shell-nix.md
@@ -0,0 +1,28 @@
+---
+synopsis: "`nix-shell <directory>` looks for `shell.nix`"
+significance: significant
+issues:
+- 496
+- 2279
+- 4529
+- 5431
+- 11053
+prs:
+- 11057
+---
+
+`nix-shell $x` now looks for `$x/shell.nix` when `$x` resolves to a directory.
+
+Although this might be seen as a breaking change, its primarily interactive usage makes it a minor issue.
+This adjustment addresses a commonly reported problem.
+
+This also applies to `nix-shell` shebang scripts. Consider the following example:
+
+```shell
+#!/usr/bin/env nix-shell
+#!nix-shell -i bash
+```
+
+This will now load `shell.nix` from the script's directory, if it exists; `default.nix` otherwise.
+
+The old behavior can be opted into by setting the option [`nix-shell-always-looks-for-shell-nix`](@docroot@/command-ref/conf-file.md#conf-nix-shell-always-looks-for-shell-nix) to `false`.

From 0f8a655023be204499c6360e072b36f58f6f194c Mon Sep 17 00:00:00 2001
From: Robert Hensing <robert@roberthensing.nl>
Date: Sun, 7 Jul 2024 13:02:21 +0200
Subject: [PATCH 20/25] tests/functional/shell.nix: Implement runHook for dummy
 stdenv

---
 tests/functional/shell.nix | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/tests/functional/shell.nix b/tests/functional/shell.nix
index 75e3845ea..1fb00c5a3 100644
--- a/tests/functional/shell.nix
+++ b/tests/functional/shell.nix
@@ -26,6 +26,9 @@ let pkgs = rec {
     fun() {
       echo blabla
     }
+    runHook() {
+      eval "''${!1}"
+    }
   '';
 
   stdenv = mkDerivation {

From e1106b45a31228c6f5fe8be0bd5fbde08e7c3255 Mon Sep 17 00:00:00 2001
From: Robert Hensing <robert@roberthensing.nl>
Date: Sun, 7 Jul 2024 13:03:19 +0200
Subject: [PATCH 21/25] tests/functional/nix-shell.sh: Fix Polo test for VM
 test

It is unclear to me why this worked when not in a VM test, but the
explanation would be in the part of nix-shell we're getting rid of
with the devShell attribute.
---
 tests/functional/shell.nix | 1 +
 1 file changed, 1 insertion(+)

diff --git a/tests/functional/shell.nix b/tests/functional/shell.nix
index 1fb00c5a3..750cdf0bc 100644
--- a/tests/functional/shell.nix
+++ b/tests/functional/shell.nix
@@ -56,6 +56,7 @@ let pkgs = rec {
   # See nix-shell.sh
   polo = mkDerivation {
     name = "polo";
+    inherit stdenv;
     shellHook = ''
       echo Polo
     '';

From 193dd5d9342e4ee7892b391d32240bbc431f16c8 Mon Sep 17 00:00:00 2001
From: Robert Hensing <robert@roberthensing.nl>
Date: Sun, 7 Jul 2024 14:49:52 +0200
Subject: [PATCH 22/25] Fixup: add missing test file

---
 tests/functional/shell.shebang.legacy.expr | 10 ++++++++++
 1 file changed, 10 insertions(+)
 create mode 100755 tests/functional/shell.shebang.legacy.expr

diff --git a/tests/functional/shell.shebang.legacy.expr b/tests/functional/shell.shebang.legacy.expr
new file mode 100755
index 000000000..490542f43
--- /dev/null
+++ b/tests/functional/shell.shebang.legacy.expr
@@ -0,0 +1,10 @@
+#! @ENV_PROG@ nix-shell
+#! nix-shell "{ script, path, ... }: assert path == ./shell.nix; script { fooContents = toString ./.; }"
+#! nix-shell --no-substitute
+#! nix-shell --expr
+#! nix-shell --arg script "import ((builtins.getEnv ''TEST_ROOT'')+''/shell.nix'')"
+#! nix-shell --arg path "./shell.nix"
+#! nix-shell -A shellDrv
+#! nix-shell -i bash
+#! nix-shell --option nix-shell-shebang-arguments-relative-to-script false
+echo "$FOO"

From c4e3e2dc27da93cae22cd35a11ee1ef87e23eb57 Mon Sep 17 00:00:00 2001
From: Robert Hensing <robert@roberthensing.nl>
Date: Wed, 10 Jul 2024 16:24:31 +0200
Subject: [PATCH 23/25] Soft-deprecate the compatibility settings

---
 src/libcmd/compatibility-settings.hh | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/src/libcmd/compatibility-settings.hh b/src/libcmd/compatibility-settings.hh
index 961001080..0506743f3 100644
--- a/src/libcmd/compatibility-settings.hh
+++ b/src/libcmd/compatibility-settings.hh
@@ -7,14 +7,18 @@ struct CompatibilitySettings : public Config
 
     CompatibilitySettings() = default;
 
+    // Added in Nix 2.24, July 2024.
     Setting<bool> nixShellAlwaysLooksForShellNix{this, true, "nix-shell-always-looks-for-shell-nix", R"(
         Before Nix 2.24, [`nix-shell`](@docroot@/command-ref/nix-shell.md) would only look at `shell.nix` if it was in the working directory - when no file was specified.
 
         Since Nix 2.24, `nix-shell` always looks for a `shell.nix`, whether that's in the working directory, or in a directory that was passed as an argument.
 
         You may set this to `false` to revert to the Nix 2.3 behavior.
+
+        This setting is not recommended, and will be deprecated and later removed in the future.
     )"};
 
+    // Added in Nix 2.24, July 2024.
     Setting<bool> nixShellShebangArgumentsRelativeToScript{
         this, true, "nix-shell-shebang-arguments-relative-to-script", R"(
         Before Nix 2.24, the arguments in a `nix-shell` shebang - as well as `--arg` - were relative to working directory.
@@ -22,6 +26,8 @@ struct CompatibilitySettings : public Config
         Since Nix 2.24, the arguments are relative to the [base directory](@docroot@/glossary.md#gloss-base-directory) defined as the script's directory.
 
         You may set this to `false` to revert to the Nix 2.3 behavior.
+
+        This setting is not recommended, and will be deprecated and later removed in the future.
     )"};
 };
 

From 6f5f741157ff14e8a67608be9bee2bfc8d5778a8 Mon Sep 17 00:00:00 2001
From: Robert Hensing <robert@roberthensing.nl>
Date: Thu, 11 Jul 2024 13:51:03 +0200
Subject: [PATCH 24/25] doc/rl-next/shebang-relative: Update with example

---
 doc/manual/rl-next/shebang-relative.md | 64 +++++++++++++++++++++++---
 1 file changed, 58 insertions(+), 6 deletions(-)

diff --git a/doc/manual/rl-next/shebang-relative.md b/doc/manual/rl-next/shebang-relative.md
index ab39a359c..c887a598a 100644
--- a/doc/manual/rl-next/shebang-relative.md
+++ b/doc/manual/rl-next/shebang-relative.md
@@ -1,10 +1,62 @@
-synopsis: ensure nix-shell shebang uses relative path
-prs: #5088
-description: {
+---
+synopsis: "`nix-shell` shebang uses relative path"
+prs:
+- 5088
+- 11058
+issues:
+- 4232
+---
 
-`nix-shell` shebangs use the script file's relative location to resolve relative paths to files passed as command line arguments, but expression arguments were still evaluated using the current working directory as a base path.
-The new behavior is that evaluations are performed relative to the script.
+<!-- unfortunately no link target for the specific syntax -->
+Relative [path](@docroot@/language/values.md#type-path) literals in `nix-shell` shebang scripts' options are now resolved relative to the [script's location](@docroot@/glossary?highlight=base%20directory#gloss-base-directory).
+Previously they were resolved relative to the current working directory.
 
+For example, consider the following script in `~/myproject/say-hi`:
+
+```shell
+#!/usr/bin/env nix-shell
+#!nix-shell --expr 'import ./shell.nix'
+#!nix-shell --arg toolset './greeting-tools.nix'
+#!nix-shell -i bash
+hello
+```
+
+Older versions of `nix-shell` would resolve `shell.nix` relative to the current working directory; home in this example:
+
+```console
+[hostname:~]$ ./myproject/say-hi
+error:
+       … while calling the 'import' builtin
+         at «string»:1:2:
+            1| (import ./shell.nix)
+             |  ^
+
+       error: path '/home/user/shell.nix' does not exist
+```
+
+Since this release, `nix-shell` resolves `shell.nix` relative to the script's location, and `~/myproject/shell.nix` is used.
+
+```console
+$ ./myproject/say-hi
+Hello, world!
+```
+
+**Opt-out**
+
+This is technically a breaking change, so we have added an option so you can adapt independently of your Nix update.
 The old behavior can be opted into by setting the option [`nix-shell-shebang-arguments-relative-to-script`](@docroot@/command-ref/conf-file.md#conf-nix-shell-shebang-arguments-relative-to-script) to `false`.
+This option will be removed in a future release.
 
-}
+**`nix` command shebang**
+
+The experimental [`nix` command shebang](@docroot@/command-ref/new-cli/nix.md?highlight=shebang#shebang-interpreter) already behaves in this script-relative manner.
+
+Example:
+
+```shell
+#!/usr/bin/env nix
+#!nix develop
+#!nix --expr ``import ./shell.nix``
+#!nix -c bash
+hello
+```

From bb312a717451fc88f1220e1ce56700eaaf15e3de Mon Sep 17 00:00:00 2001
From: Robert Hensing <robert@roberthensing.nl>
Date: Thu, 11 Jul 2024 13:53:03 +0200
Subject: [PATCH 25/25] Edit CompatibilitySettings

---
 src/libcmd/compatibility-settings.hh | 14 ++++++++------
 1 file changed, 8 insertions(+), 6 deletions(-)

diff --git a/src/libcmd/compatibility-settings.hh b/src/libcmd/compatibility-settings.hh
index 0506743f3..a129a957a 100644
--- a/src/libcmd/compatibility-settings.hh
+++ b/src/libcmd/compatibility-settings.hh
@@ -13,21 +13,23 @@ struct CompatibilitySettings : public Config
 
         Since Nix 2.24, `nix-shell` always looks for a `shell.nix`, whether that's in the working directory, or in a directory that was passed as an argument.
 
-        You may set this to `false` to revert to the Nix 2.3 behavior.
+        You may set this to `false` to temporarily revert to the behavior of Nix 2.23 and older.
 
-        This setting is not recommended, and will be deprecated and later removed in the future.
+        Using this setting is not recommended.
+        It will be deprecated and removed.
     )"};
 
     // Added in Nix 2.24, July 2024.
     Setting<bool> nixShellShebangArgumentsRelativeToScript{
         this, true, "nix-shell-shebang-arguments-relative-to-script", R"(
-        Before Nix 2.24, the arguments in a `nix-shell` shebang - as well as `--arg` - were relative to working directory.
+        Before Nix 2.24, relative file path expressions in arguments in a `nix-shell` shebang were resolved relative to the working directory.
 
-        Since Nix 2.24, the arguments are relative to the [base directory](@docroot@/glossary.md#gloss-base-directory) defined as the script's directory.
+        Since Nix 2.24, `nix-shell` resolves these paths in a manner that is relative to the [base directory](@docroot@/glossary.md#gloss-base-directory), defined as the script's directory.
 
-        You may set this to `false` to revert to the Nix 2.3 behavior.
+        You may set this to `false` to temporarily revert to the behavior of Nix 2.23 and older.
 
-        This setting is not recommended, and will be deprecated and later removed in the future.
+        Using this setting is not recommended.
+        It will be deprecated and removed.
     )"};
 };