Update documentation for paths on command line

Co-authored-by: Théophane Hufschmitt <7226587+thufschmitt@users.noreply.github.com>
This commit is contained in:
Alexander Bantyev 2022-01-17 20:00:04 +03:00 committed by GitHub
parent b9f5dccdbe
commit 34b66aab00
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23

View file

@ -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*