docs: clarify how ^ works for -E/-f installables

We didn't even realize you *could* use this syntax with -E and -f, much
less that the attribute path could be *empty*.

Change-Id: Id1a6715609f3a76a5ce477bd43a7832effbbe07b

1 files changed, 17 insertions, 3 deletions

diff --git a/src/nix/nix.md b/src/nix/nix.md
index 65fe0c5b5..0d588cd01 100644
--- a/src/nix/nix.md
+++ b/src/nix/nix.md
@@ -192,9 +192,10 @@ that contains programs, and a `dev` output that provides development
 artifacts like C/C++ header files. The outputs on which `nix` commands
 operate are determined as follows:
 
-* You can explicitly specify the desired outputs using the syntax
-  *installable*`^`*output1*`,`*...*`,`*outputN*. For example, you can
-  obtain the `dev` and `static` outputs of the `glibc` package:
+* You can explicitly specify the desired outputs using the syntax *installable*`^`*output1*`,`*...*`,`*outputN* — that is, a caret followed immediately by a comma-separated list of derivation outputs to select.
+  For installables specified as [Flake output attributes](#flake-output-attribute) or [Store paths](#store-path), the output is specified in the same argument:
+
+  For example, you can obtain the `dev` and `static` outputs of the `glibc` package:
 
   ```console
   # nix build 'nixpkgs#glibc^dev,static'
@@ -209,6 +210,19 @@ operate are determined as follows:
   …
   ```
 
+  For `-e`/`--expr` and `-f`/`--file`, the derivation output is specified as part of the attribute path:
+
+  ```console
+  $ nix build -f '<nixpkgs>' 'glibc^dev,static'
+  $ nix build --impure -E 'import <nixpkgs> { }' 'glibc^dev,static'
+  ```
+
+  This syntax is the same even if the actual attribute path is empty:
+
+  ```console
+  $ nix build -E 'let pkgs = import <nixpkgs> { }; in pkgs.glibc' '^dev,static'
+  ```
+
 * You can also specify that *all* outputs should be used using the
   syntax *installable*`^*`. For example, the following shows the size
   of all outputs of the `glibc` package in the binary cache: