From 38bb7f532c480714e7adaa9a2ea108bd166029b3 Mon Sep 17 00:00:00 2001
From: Robert Hensing <robert@roberthensing.nl>
Date: Wed, 26 Nov 2025 22:19:29 +0100
Subject: [PATCH] Document and test -- separator behavior with installables

Clarifies that the first positional argument is always treated as the
installable, even after --. Adds tests to prevent accidental change.

Addresses https://github.com/NixOS/nix/issues/13994
---
 src/nix/run.md                 | 10 ++++++++++
 tests/functional/flakes/run.sh | 34 ++++++++++++++++++++++++++++++++++
 2 files changed, 44 insertions(+)

diff --git a/src/nix/run.md b/src/nix/run.md
index eb96e6b31..179980010 100644
--- a/src/nix/run.md
+++ b/src/nix/run.md
@@ -33,6 +33,16 @@ R""(
   # nix run nixpkgs#vim -- --help
   ```
 
+* Run the default app from the current directory with arguments:
+
+  ```console
+  # nix run . -- arg1 arg2
+  ```
+
+  Note: The first positional argument is always treated as the *installable*,
+  even after `--`. To pass arguments to the default installable, specify it
+  explicitly: `nix run . -- arg1 arg2` or `nix run -- . arg1 arg2`.
+
 # Description
 
 `nix run` builds and runs [*installable*](./nix.md#installables), which must evaluate to an
diff --git a/tests/functional/flakes/run.sh b/tests/functional/flakes/run.sh
index 107b3dfb8..1de6f2844 100755
--- a/tests/functional/flakes/run.sh
+++ b/tests/functional/flakes/run.sh
@@ -55,5 +55,39 @@ echo "_=..." >> "$TEST_ROOT"/actual-env
 sort "$TEST_ROOT"/actual-env | uniq > "$TEST_ROOT"/actual-env.sorted
 diff "$TEST_ROOT"/expected-env.sorted "$TEST_ROOT"/actual-env.sorted
 
+# Test for issue #13994: verify behavior of -- separator with installable
+# Create a flake with an app that prints its arguments
 clearStore
+rm -rf "$TEST_HOME"/.cache "$TEST_HOME"/.config "$TEST_HOME"/.local
+cd "$TEST_HOME"
+
+cat <<'EOF' > print-args.sh
+#!/bin/sh
+printf "ARGS:"
+for arg in "$@"; do
+    printf " %s" "$arg"
+done
+printf "\n"
+EOF
+chmod +x print-args.sh
+
+cat <<EOF > flake.nix
+{
+  outputs = {self}: {
+    apps.$system.default = {
+      type = "app";
+      program = "\${self}/print-args.sh";
+    };
+  };
+}
+EOF
+
+# Test correct usage: installable before --
+nix run --no-write-lock-file . -- myarg1 myarg2 2>&1 | grepQuiet "ARGS: myarg1 myarg2"
+
+# Test that first positional argument is still treated as installable after -- (issue #13994)
+nix run --no-write-lock-file -- . myarg1 myarg2 2>&1 | grepQuiet "ARGS: myarg1 myarg2"
+
+# And verify that a non-installable first argument causes an error
+expectStderr 1 nix run --no-write-lock-file -- myarg1 myarg2 | grepQuiet "error.*myarg1"