query
On this page

fetchTree

builtins.fetchTree

Primop
Experimental
Docs pulled from | This Revision | about 5 hours ago

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. If narHash 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 or rev is given, Nix will only consider files added to the Git index, as listed by git 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 and allRefs 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 any ref. (Without setting this option, only revs from the specified ref 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"
This function is not defined in a .nix file. It is likely a builtins function or an alias of a builtins function. builtins functions are predefined functions provided by Nix.

Implementation

This function is implemented in c++ and is part of the native nix runtime.