nix-shell: Add --run flag

‘--run’ is like ‘--command’, except that it runs the command in a
non-interactive shell. This is important if you do things like:

  $ nix-shell --command make

Hitting Ctrl-C while make is running drops you into the interactive
Nix shell, which is probably not what you want. So you can now do

  $ nix-shell --run make

instead.

1 files changed, 19 insertions, 5 deletions

diff --git a/doc/manual/command-ref/nix-shell.xml b/doc/manual/command-ref/nix-shell.xml
index 1f03117636c9..c1b172b70380 100644
--- a/doc/manual/command-ref/nix-shell.xml
+++ b/doc/manual/command-ref/nix-shell.xml
@@ -29,6 +29,7 @@
       <replaceable>attrPath</replaceable>
     </arg>
     <arg><option>--command</option> <replaceable>cmd</replaceable></arg>
+    <arg><option>--run</option> <replaceable>cmd</replaceable></arg>
     <arg><option>--exclude</option> <replaceable>regexp</replaceable></arg>
     <arg><option>--pure</option></arg>
     <group choice='req'>
@@ -92,11 +93,24 @@ also <xref linkend="sec-common-options" />.</phrase></para>
   <varlistentry><term><option>--command</option> <replaceable>cmd</replaceable></term>
 
     <listitem><para>In the environment of the derivation, run the
-    shell command <replaceable>cmd</replaceable> instead of starting
-    an interactive shell.  However, if you end the shell command with
-    <literal>return</literal>, you still get an interactive shell.
-    This can be useful for doing any additional
-    initialisation.</para></listitem>
+    shell command <replaceable>cmd</replaceable>. This command is
+    executed in an interactive shell. (Use <option>--run</option> to
+    use a non-interactive shell instead.) However, a call to
+    <literal>exit</literal> is implicitly added to the command, so the
+    shell will exit after running the command. To prevent this, add
+    <literal>return</literal> at the end; e.g. <literal>--command
+    "echo Hello; return"</literal> will print <literal>Hello</literal>
+    and then drop you into the interactive shell. This can be useful
+    for doing any additional initialisation.</para></listitem>
+
+  </varlistentry>
+
+  <varlistentry><term><option>--run</option> <replaceable>cmd</replaceable></term>
+
+    <listitem><para>Like <option>--command</option>, but executes the
+    command in a non-interactive shell. This means (among other
+    things) that if you hit Ctrl-C while the command is running, the
+    shell exits.</para></listitem>
 
   </varlistentry>