Merge pull request #755 from fricklerhandwerk/move-direnv-recipe

move direnv instructions to recipes, update and rework text

source/recipes/direnv.md

@@ -0,0 +1,63 @@
+(direnv)=
+# Automatic environment activation with `direnv`
+
+Instead of manually activating the environment for each project, you can reload a [declarative shell](declarative-reproducible-envs) every time you enter the project's directory or change the `shell.nix` inside it.
+
+1. [Make nix-direnv available](https://github.com/nix-community/nix-direnv)
+2. [Hook it into your shell](https://direnv.net/docs/hook.html)
+
+For example, write a `shell.nix` with the following contents:
+
+```nix
+let
+  nixpkgs = fetchTarball "https://github.com/NixOS/nixpkgs/tarball/nixos-22.11";
+  pkgs = import nixpkgs { config = {}; overlays = []; };
+in
+
+pkgs.mkShell {
+  packages = with pkgs; [
+    hello
+  ];
+}
+
+```
+From the top-level directory of your project run:
+
+```shell-session
+$ echo "use nix" > .envrc && direnv allow
+```
+
+The next time you launch your terminal and enter the top-level directory of your project, `direnv` will automatically launch the shell defined in `shell.nix`
+
+```shell-session
+$ cd myproject
+$ which hello
+/nix/store/1gxz5nfzfnhyxjdyzi04r86sh61y4i00-hello-2.12.1/bin/hello
+```
+
+`direnv` will also check for changes to the `shell.nix` file.
+
+Make the following addition:
+
+```diff
+ let
+   nixpkgs = fetchTarball "https://github.com/NixOS/nixpkgs/tarball/nixos-22.11";
+   pkgs = import nixpkgs { config = {}; overlays = []; };
+ in
+
+ pkgs.mkShell {
+   packages = with pkgs; [
+     hello
+   ];
++
++  shellHook = ''
++    hello
++  '';
+ }
+```
+
+The running environment should reload itself after the first interaction (run any command or press `Enter`).
+
+```shell-session
+Hello, world!
+```

source/recipes/index.md

@@ -11,4 +11,5 @@ These sections contains guides to getting things done.
 ./faq.md
 ../templates/*
 ./troubleshooting.md
+./direnv.md
 ```

source/tutorials/learning-journey/sharing-dependencies.md

@@ -205,4 +205,4 @@ You will likely see different store paths and versions depending on when you exe
 ## Next steps
 - [Nixpkgs Manual - `mkShell`](https://nixos.org/manual/nixpkgs/stable/#sec-pkgs-mkShell)
 - [Nix Pills - callPackage Design Pattern][nix_pills_callpackage]
-- [Creating shell environments](https://nix.dev/tutorials/learning-journey/shell-dot-nix.html)
+- [Creating shell environments](https://nix.dev/tutorials/first-steps/declarative-shell.html)