Nix Flake Types: Path and Git

entry in the registry; see [nix registry](./nix3-registry.md) for details. For example, these are valid indirect flake references: * `nixpkgs` * `nixpkgs/nixos-unstable` * `nixpkgs/a3a3dda3bacf61e8a39258a0ed9c924eeca8e293` * `nixpkgs/nixos-unstable/a3a3dda3bacf61e8a39258a0ed9c924eeca8e293` * `sub/dir` (if a flake named `sub` is in the registry) * <a name="path-fetcher"></a>`path`: arbitrary local directories. The required attribute `path` specifies the path of the flake. The URL form is ``` path:<path>(\?<params>)? ``` where *path* is an absolute path to a directory in the file system containing a file named `flake.nix`. If the flake at *path* is not inside a git repository, the `path:` prefix is implied and can be omitted. If *path* is a relative path (i.e. if it does not start with `/`), it is interpreted as follows: - If *path* is a command line argument, it is interpreted relative to the current directory. - If *path* is used in a `flake.nix`, it is interpreted relative to the directory containing that `flake.nix`. However, the resolved path must be in the same tree. For instance, a `flake.nix` in the root of a tree can use `path:./foo` to access the flake in subdirectory `foo`, but `path:../bar` is illegal. On the other hand, a flake in the `/foo` directory of a tree can use `path:../bar` to refer to the flake in `/bar`. Path inputs can be specified with path values in `flake.nix`. Path values are a syntax for `path` inputs, and they are converted by 1. resolving them into relative paths, relative to the base directory of `flake.nix` 2. escaping URL characters (refer to IETF RFC?) 3. prepending `path:` Note that the allowed syntax for path values in flake `inputs` may be more restrictive than general Nix, so you may need to use `path:` if your path contains certain special characters. See [Path literals](@docroot@/language/syntax.md#path-literal) Note that if you omit `path:`, relative paths must start with `.` to avoid ambiguity with registry lookups (e.g. `nixpkgs` is a registry lookup; `./nixpkgs` is a relative path). For example, these are valid path flake references: * `path:/home/user/sub/dir` * `/home/user/sub/dir` (if `dir/flake.nix` is *not* in a git repository) * `path:sub/dir` * `./sub/dir` * `path:../parent` * `git`: Git repositories. The location of the repository is specified by the attribute `url`. They have the URL form ``` git(+http|+https|+ssh|+git|+file):(//<server>)?<path>(\?<params>)? ``` If *path* starts with `/` (or `./` when used as an argument on the command line) and is a local path to a git repository, the leading `git:` or `+file` prefixes are implied and can be omitted. The `ref` attribute defaults to resolving the `HEAD` reference. The `rev` attribute must denote a commit that exists in the branch or tag specified by the `ref` attribute, since Nix doesn't do a full clone of the remote repository by default (and the Git protocol doesn't allow fetching a `rev` without a known `ref`). The default is the commit currently pointed to by `ref`. When `git+file` is used without specifying `ref` or `rev`, files are fetched directly from the local `path` as long as they have been added to the Git repository. If there are uncommitted changes, the reference is treated as dirty and a warning is printed. For example, the following are valid Git flake references: * `git:/home/user/sub/dir` * `/home/user/sub/dir` (if `dir/flake.nix` is in a git repository) * `./sub/dir` (when used on the command line and `dir/flake.nix` is in a git repository) * `git+https://example.org/my/repo` * `git+https://example.org/my/repo?dir=flake1` * `git+https://example.org/my/repo?shallow=1` A shallow clone of the repository. For large repositories, the shallow clone option can significantly speed up fresh clones compared to non-shallow clones, while still providing faster updates than other fetch methods such as `tarball:` or `github:`.

This section elaborates on the `path` and `git` flake types in Nix. It explains how `path` flakes refer to local directories and how relative paths are resolved within `flake.nix` files. It also covers path values, their conversion process, and potential syntax restrictions. The section then details `git` flakes, specifying how to reference Git repositories using URLs, including local paths. It explains the roles of `ref` and `rev` attributes, the behavior of `git+file`, and the use of shallow clones for large repositories. Examples are provided for both `path` and `git` flake references.