Nix Flake Reference Types: Git, Mercurial, Tarball, File, GitHub, and GitLab

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:`. * `git+ssh://git@github.com/NixOS/nix?ref=v1.2.3` * `git://github.com/edolstra/dwarffs?ref=unstable&rev=e486d8d40e626a20e06d792db8cc5ac5aba9a5b4` * `git+file:///home/my-user/some-repo/some-repo` * `mercurial`: Mercurial repositories. The URL form is similar to the `git` type, except that the URL schema must be one of `hg+http`, `hg+https`, `hg+ssh` or `hg+file`. * `tarball`: Tarballs. The location of the tarball is specified by the attribute `url`. In URL form, the schema must be `tarball+http://`, `tarball+https://` or `tarball+file://`. If the extension corresponds to a known archive format (`.zip`, `.tar`, `.tgz`, `.tar.gz`, `.tar.xz`, `.tar.bz2` or `.tar.zst`), then the `tarball+` can be dropped. This can also be used to set the location of gitea/forgejo branches. [See here](@docroot@/protocols/tarball-fetcher.md#gitea-and-forgejo-support) * `file`: Plain files or directory tarballs, either over http(s) or from the local disk. In URL form, the schema must be `file+http://`, `file+https://` or `file+file://`. If the extension doesn’t correspond to a known archive format (as defined by the `tarball` fetcher), then the `file+` prefix can be dropped. * `github`: A more efficient way to fetch repositories from GitHub. The following attributes are required: * `owner`: The owner of the repository. * `repo`: The name of the repository. These are downloaded as tarball archives, rather than through Git. This is often much faster and uses less disk space since it doesn't require fetching the entire history of the repository. On the other hand, it doesn't allow incremental fetching (but full downloads are often faster than incremental fetches!). The URL syntax for `github` flakes is: ``` github:<owner>/<repo>(/<rev-or-ref>)?(\?<params>)? ``` `<rev-or-ref>` specifies the name of a branch or tag (`ref`), or a commit hash (`rev`). Note that unlike Git, GitHub allows fetching by commit hash without specifying a branch or tag. You can also specify `host` as a parameter, to point to a custom GitHub Enterprise server. Some examples: * `github:edolstra/dwarffs` * `github:edolstra/dwarffs/unstable` * `github:edolstra/dwarffs/d3f2baba8f425779026c6ec04021b2e927f61e31` * `github:internal/project?host=company-github.example.org` * `gitlab`: Similar to `github`, is a more efficient way to fetch GitLab repositories. The following attributes are required: * `owner`: The owner of the repository. * `repo`: The name of the repository. Like `github`, these are downloaded as tarball archives. The URL syntax for `gitlab` flakes is: `gitlab:<owner>/<repo>(/<rev-or-ref>)?(\?<params>)?` `<rev-or-ref>` works the same as `github`. Either a branch or tag name (`ref`), or a commit hash (`rev`) can be specified. Since GitLab allows for self-hosting, you can specify `host` as a parameter, to point to any instances other than `gitlab.com`.

This chunk continues the discussion on Nix flake reference types, providing further examples for `git` references, including `git+ssh` and `git+file`, and detailing behavior for local `git+file` references with uncommitted changes. It then introduces `mercurial` repositories, which have URL forms similar to `git` but use `hg+` schemas. `tarball` references are explained for fetching archive files, specifying URL schemas like `tarball+http://` and allowing the prefix to be dropped for common archive extensions. `file` references are described for plain files or directory tarballs, with similar URL schema conventions. Finally, it covers `github` and `gitlab` references as efficient ways to fetch repositories from these platforms, which download tarball archives instead of full Git histories. Both require `owner` and `repo` attributes, support a `rev-or-ref` parameter for branches, tags, or commit hashes, and allow specifying a custom `host` for enterprise or self-hosted instances.