fetchTree
builtins.fetchTree
Takes 1 arguments
input
Fetch a file system tree or a plain file using one of the supported backends and return an attribute set with:
- the resulting fixed-output store path
- the corresponding NAR hash
- backend-specific metadata (currently not documented).
input must be an attribute set with the following attributes:
-
type
(String, required)One of the supported source types. This determines other required and allowed input attributes.
-
narHash
(String, optional)The
narHash
parameter can be used to substitute the source of the tree. It also allows for verification of tree contents that may not be provided by the underlying transfer mechanism. IfnarHash
is set, the source is first looked up is the Nix store and substituters, and only fetched if not available.
A subset of the output attributes of fetchTree
can be re-used for subsequent calls to fetchTree
to produce the same result again.
That is, fetchTree
is idempotent.
Downloads are cached in $XDG_CACHE_HOME/nix
.
The remote source will be fetched from the network if both are true:
-
A NAR hash is supplied and the corresponding store path is not valid, that is, not available in the store
Note
Substituters are not used in fetching.
-
There is no cache entry or the cache entry is older than
tarball-ttl
Source types
The following source types and associated input attributes are supported.
-
"file"
Place a plain file into the Nix store. This is similar to
builtins.fetchurl
-
url
(String, required)Supported protocols:
-
https
Example
fetchTree { type = "file"; url = "https://example.com/index.html"; }
-
http
Insecure HTTP transfer for legacy sources.
Warning
HTTP performs no encryption or authentication. Use a
narHash
known in advance to ensure the output has expected contents. -
file
A file on the local file system.
Example
fetchTree { type = "file"; url = "file:///home/eelco/nix/README.md"; }
-
-
-
"tarball"
Download a tar archive and extract it into the Nix store. This has the same underyling implementation as
builtins.fetchTarball
-
url
(String, required)Example
fetchTree { type = "tarball"; url = "https://github.com/NixOS/nixpkgs/tarball/nixpkgs-23.11"; }
-
-
"git"
Fetch a Git tree and copy it to the Nix store. This is similar to
builtins.fetchGit
.-
url
(String, required)The URL formats supported are the same as for Git itself.
Example
fetchTree { type = "git"; url = "[email protected]:NixOS/nixpkgs.git"; }
Note
If the URL points to a local directory, and no
ref
orrev
is given, Nix will only consider files added to the Git index, as listed bygit ls-files
but use the current file contents of the Git working directory. -
ref
(String, optional)By default, this has no effect. This becomes relevant only once
shallow
cloning is disabled.A Git reference, such as a branch or tag name.
Default:
"HEAD"
-
rev
(String, optional)A Git revision; a commit hash.
Default: the tip of
ref
-
shallow
(Bool, optional)Make a shallow clone when fetching the Git tree. When this is enabled, the options
ref
andallRefs
have no effect anymore.Default:
true
-
submodules
(Bool, optional)Also fetch submodules if available.
Default:
false
-
allRefs
(Bool, optional)By default, this has no effect. This becomes relevant only once
shallow
cloning is disabled.Whether to fetch all references (eg. branches and tags) of the repository. With this argument being true, it's possible to load a
rev
from anyref
. (Without setting this option, onlyrev
s from the specifiedref
are supported).Default:
false
-
lastModified
(Integer, optional)Unix timestamp of the fetched commit.
If set, pass through the value to the output attribute set. Otherwise, generated from the fetched Git tree.
-
revCount
(Integer, optional)Number of revisions in the history of the Git repository before the fetched commit.
If set, pass through the value to the output attribute set. Otherwise, generated from the fetched Git tree.
-
The following input types are still subject to change:
"path"
"github"
"gitlab"
"sourcehut"
"mercurial"
input can also be a URL-like reference.
The additional input types and the URL-like syntax requires the flakes
experimental feature to be enabled.
Example
Fetch a GitHub repository using the attribute set representation:
builtins.fetchTree { type = "github"; owner = "NixOS"; repo = "nixpkgs"; rev = "ae2e6b3958682513d28f7d633734571fb18285dd"; }
This evaluates to the following attribute set:
{ lastModified = 1686503798; lastModifiedDate = "20230611171638"; narHash = "sha256-rA9RqKP9OlBrgGCPvfd5HVAXDOy8k2SmPtB/ijShNXc="; outPath = "/nix/store/l5m6qlvfs9sdw14ja3qbzpglcjlb6j1x-source"; rev = "ae2e6b3958682513d28f7d633734571fb18285dd"; shortRev = "ae2e6b3"; }
Example
Fetch the same GitHub repository using the URL-like syntax:
builtins.fetchTree "github:NixOS/nixpkgs/ae2e6b3958682513d28f7d633734571fb18285dd"
Implementation
This function is implemented in c++ and is part of the native nix runtime.