From 34b66aab009428d3fab05b7530d6d13f1df3b2c9 Mon Sep 17 00:00:00 2001
From: Alexander Bantyev <balsoft@balsoft.ru>
Date: Mon, 17 Jan 2022 20:00:04 +0300
Subject: [PATCH] Update documentation for paths on command line
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-authored-by: Théophane Hufschmitt <7226587+thufschmitt@users.noreply.github.com>
---
 src/nix/nix.md | 54 +++++++++++++++++++++++++++++++-------------------
 1 file changed, 34 insertions(+), 20 deletions(-)

diff --git a/src/nix/nix.md b/src/nix/nix.md
index 0756ef0ac..33942a5ad 100644
--- a/src/nix/nix.md
+++ b/src/nix/nix.md
@@ -63,27 +63,41 @@ the Nix store. Here are the recognised types of installables:
   (e.g. `github:nixos/nixpkgs` or `path:.`)
 
   When the flake reference is a raw path (a path without any URL
-  scheme), it is interpreted in the following way:
+  scheme), it is interpreted as a `path:` or `git+file:` url in the following
+  way:
+  
+  - If the path is within a Git repository, then the url will be of the form
+    `git+file://[GIT_REPO_ROOT]?dir=[RELATIVE_FLAKE_DIR_PATH]`
+    where `GIT_REPO_ROOT` is the path to the root of the git repository,
+    and `RELATIVE_FLAKE_DIR_PATH` is the path (relative to the directory
+    root) of the closest parent of the given path that contains a `flake.nix` within
+    the git repository.
+    If no such directory exists, then Nix will error-out.
+    
+    Note that the search will only include files indexed by git. In particular, files
+    which are matched by `.gitignore` or have never been `git add`-ed will not be
+    available in the flake. If this is undesireable, specify `path:<directory>` explicitly;
+    
+    For example, if `/foo/bar` is a git repository with the following structure:
+    ```
+   .
+   └── baz
+       ├── blah
+       │   └── file.txt
+       └── flake.nix
+    ```
+
+  Then `/foo/bar/baz/blah` will resolve to `git+file:///foo/bar?dir=baz`
+
+  - If the supplied path is not a git repository, then the url will have the form
+    `path:FLAKE_DIR_PATH` where `FLAKE_DIR_PATH` is the closest parent
+    of the supplied path that contains a `flake.nix` file (within the same file-system).
+    If no such directory exists, then Nix will error-out.
+    
+    For example, if `/foo/bar/flake.nix` exists, then `/foo/bar/baz/` will resolve to
+   `path:/foo/bar`
+
 
-  - If the supplied path does not contain `flake.nix`, then Nix
-    searches for a directory containing `flake.nix` upwards of the
-    supplied path (until a filesystem boundary or a git repository
-    root). For example, if `/foo/bar/flake.nix` exists, then supplying
-    `/foo/bar/baz/` will find the directory `/foo/bar/`;
-  - If `flake.nix` is in a Git repository, then this is essentially
-    equivalent to `git+file://<directory>` (see [the `nix flake`
-    manual page](./nix3-flake.md)), except that the `dir` parameter is
-    derived automatically. For example, if `/foo/bar` is a Git
-    repository and `/foo/bar/baz` contains `flake.nix`, then the flake
-    reference `/foo/bar/baz` is equivalent to
-    `git+file:///foo/bar?dir=baz`. Note that it will only include
-    files indexed by git. In particular, files which are matched by
-    `.gitignore` will not be available in the flake. If this is
-    undesireable, specify `path:<directory>` explicitly;
-  - If the directory is not inside a Git repository, then it is
-    equivalent to `path:<directory>` (see [the `nix flake` manual
-    page](./nix3-flake.md)), which includes the entire contents of the
-    path.
 
   If *attrpath* is omitted, Nix tries some default values; for most
   subcommands, the default is `defaultPackage.`*system*