docs: add section about overlays in nix repl --help

I just copied and slightly edited the `man nix.conf(5)` docs about `repl-overlays` to the nix repl help text (but cut out the more complicated example and redirecting to the nix.conf docs for more info). Fixes #303 Change-Id: I85efaef606d8779ac66fe72cd3947d663f33fa44
2026-03-27 10:41:45 +00:00
parent 03ab7b4a76
commit 001e3fde8f
1 changed files with 65 additions and 0 deletions
@@ -83,4 +83,69 @@ On startup, it loads the Nix expressions named *files* and adds them
 into the lexical scope. You can load addition files using the `:l
 <filename>` command, or reload all files using `:r`.

+# Adding default variables in REPL sessions
+
+It is possible to automatically load variables from a list of files
+into each new REPL session using the
+[`repl-overlays`](@docroot@/command-ref/conf-file.html#conf-repl-overlays)
+configuration option.
+
+Each file should contain a Nix function taking three taking and
+returning an
+[attribute set](@docroot@/language/values.html#attribute-set).
+These three arguments are:
+
+1. An [attribute set](@docroot@/language/values.html#attribute-set)
+    containing at least a `currentSystem` attribute (this is identical
+    to
+    [`builtins.currentSystem`](@docroot@/language/builtin-constants.md#builtins-currentSystem),
+    except that it's available in
+    [`pure-eval`](@docroot@/command-ref/conf-file.html#conf-pure-eval)
+    mode).
+2. The top-level bindings produced by the previous `repl-overlays`
+    value (or the default top-level bindings).
+3. The final top-level bindings produced by calling all
+    `repl-overlays`.
+
+## Examples
+
+* Aliasing `legacyPackages.${currentSystem}` to `pkgs`
+
+  A file named `/home/alice/my-overlays.nix` containing the following code
+  would, if `legacyPackages` exists, add a variable named `pkgs` into
+  the global REPL scope, which returns the value of
+  `legacyPackages.${currentSystem}`.
+
+  ```nix
+  info: final: prev:
+  if prev ? legacyPackages
+    && prev.legacyPackages ? ${info.currentSystem}
+  then
+  {
+    pkgs = prev.legacyPackages.${info.currentSystem};
+  }
+  else
+  { }
+  ```
+
+  This file can be loaded automatically for every REPL session by
+  adding it to the value of
+  [`repl-overlays`](@docroot@/command-ref/conf-file.html#conf-repl-overlays)
+  inside `nix.conf`. For a single session, it is possible to add it
+  using `--option repl-overlays /home/alice/my-overlay.nix`:
+
+  ```console
+  # nix repl --option repl-overlays /home/alice/my-overlay.nix nixpkgs
+
+  nix-repl> pkgs == legacyPackages.${builtins.currentSystem}
+  true
+
+  nix-repl> pkgs.hello
+  «derivation /nix/store/qdzln99hynf92vrz8sz91hlf1dmb1vdy-hello-2.12.2.drv»
+  ```
+
+See the `nix.conf`
+[`repl-overlays`](@docroot@/command-ref/conf-file.html#conf-repl-overlays)
+documentation for more information.
+
 )""