From d003321adba48aba5b1c23472a2ed76aad12e041 Mon Sep 17 00:00:00 2001
From: alex <source@proof.construction>
Date: Mon, 9 Oct 2023 13:37:21 -0500
Subject: [PATCH] move direnv instructions to recipes, update and rework text

Co-authored-by: fricklerhandwerk <valentin@fricklerhandwerk.de>
---
 source/recipes/direnv.md                      | 63 +++++++++++++++++++
 source/recipes/index.md                       |  1 +
 .../learning-journey/sharing-dependencies.md  |  2 +-
 3 files changed, 65 insertions(+), 1 deletion(-)
 create mode 100644 source/recipes/direnv.md

diff --git a/source/recipes/direnv.md b/source/recipes/direnv.md
new file mode 100644
index 0000000..69b3e1c
--- /dev/null
+++ b/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!
+```
diff --git a/source/recipes/index.md b/source/recipes/index.md
index 085539f..5a3326c 100644
--- a/source/recipes/index.md
+++ b/source/recipes/index.md
@@ -11,4 +11,5 @@ These sections contains guides to getting things done.
 ./faq.md
 ../templates/*
 ./troubleshooting.md
+./direnv.md
 ```
diff --git a/source/tutorials/learning-journey/sharing-dependencies.md b/source/tutorials/learning-journey/sharing-dependencies.md
index d1be0d2..03d46ad 100644
--- a/source/tutorials/learning-journey/sharing-dependencies.md
+++ b/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)