nix-shell: Execute shellHook if it exists

Since normal builds don't execute shellHook, this allows nix-shell
specific customisation.  Suggested by Domen.

1 files changed, 16 insertions, 0 deletions

diff --git a/doc/manual/nix-shell.xml b/doc/manual/nix-shell.xml
index e57c726f5394..4b369662e2af 100644
--- a/doc/manual/nix-shell.xml
+++ b/doc/manual/nix-shell.xml
@@ -51,6 +51,22 @@ derivation for development.</para>
 <filename>shell.nix</filename> if it exists, and
 <filename>default.nix</filename> otherwise.</para>
 
+<para>If the derivation defines the variable
+<varname>shellHook</varname>, it will be evaluated after
+<literal>$stdenv/setup</literal> has been sourced.  Since this hook is
+not executed by regular Nix builds, it allows you to perform
+initialisation specific to <command>nix-shell</command>.  For example,
+the derivation attribute
+
+<programlisting>
+shellHook =
+  ''
+    echo "Hello shell!"
+  '';
+</programlisting>
+
+will cause <command>nix-shell</command> to print <literal>Hello shell!</literal>.</para>
+
 </refsection>