Merge "Add `repl-overlays`" into main

1 files changed, 36 insertions, 0 deletions

diff --git a/doc/manual/rl-next/repl-overlays.md b/doc/manual/rl-next/repl-overlays.md
new file mode 100644
index 000000000..9f48cf381
--- /dev/null
+++ b/doc/manual/rl-next/repl-overlays.md
@@ -0,0 +1,36 @@
+---
+synopsis: Add `repl-overlays` option
+prs: 10203
+cls: 504
+---
+
+A `repl-overlays` option has been added, which specifies files that can overlay
+and modify the top-level bindings in `nix repl`. For example, with the
+following contents in `~/.config/nix/repl.nix`:
+
+```nix
+info: final: prev: let
+  optionalAttrs = predicate: attrs:
+    if predicate
+    then attrs
+    else {};
+in
+  optionalAttrs (prev ? legacyPackages && prev.legacyPackages ? ${info.currentSystem})
+  {
+    pkgs = prev.legacyPackages.${info.currentSystem};
+  }
+```
+
+We can run `nix repl` and use `pkgs` to refer to `legacyPackages.${currentSystem}`:
+
+```ShellSession
+$ nix repl --repl-overlays ~/.config/nix/repl.nix nixpkgs
+Lix 2.90.0
+Type :? for help.
+Loading installable 'flake:nixpkgs#'...
+Added 5 variables.
+Loading 'repl-overlays'...
+Added 6 variables.
+nix-repl> pkgs.bash
+«derivation /nix/store/g08b5vkwwh0j8ic9rkmd8mpj878rk62z-bash-5.2p26.drv»
+```