Document the path flakeref format (#8640)

* Document the path flakeref format Fix #8482 Co-authored-by: Valentin Gagarin <[email protected]>
NixOS · Jul 4, 2023 · 82d6699 · 82d6699
1 parent 2898dc7
commit 82d6699
Showing 1 changed file with 17 additions and 2 deletions.
diff --git a/src/nix/flake.md b/src/nix/flake.md
@@ -71,8 +71,6 @@ inputs.nixpkgs = {
 
 Here are some examples of flake references in their URL-like representation:
 
-* `.`: The flake in the current directory.
-* `/home/alice/src/patchelf`: A flake in some other directory.
 * `nixpkgs`: The `nixpkgs` entry in the flake registry.
 * `nixpkgs/a3a3dda3bacf61e8a39258a0ed9c924eeca8e293`: The `nixpkgs`
   entry in the flake registry, with its Git revision overridden to a
@@ -93,6 +91,23 @@ Here are some examples of flake references in their URL-like representation:
 * `https://github.com/NixOS/patchelf/archive/master.tar.gz`: A tarball
   flake.
 
+## Path-like syntax
+
+Flakes corresponding to a local path can also be referred to by a direct path reference, either `/absolute/path/to/the/flake` or `./relative/path/to/the/flake` (note that the leading `./` is mandatory for relative paths to avoid any ambiguity).
+
+The semantic of such a path is as follows:
+
+* If the directory is part of a Git repository, then the input will be treated as a `git+file:` URL, otherwise it will be treated as a `path:` url;
+* If the directory doesn't contain a `flake.nix` file, then Nix will search for such a file upwards in the file system hierarchy until it finds any of:
+    1. The Git repository root, or
+    2. The filesystem root (/), or
+    3. A folder on a different mount point.
+
+### Examples
+
+* `.`: The flake to which the current directory belongs to.
+* `/home/alice/src/patchelf`: A flake in some other directory.
+
 ## Flake reference attributes
 
 The following generic flake reference attributes are supported: