diff --git a/doc/manual/src/SUMMARY.md.in b/doc/manual/src/SUMMARY.md.in index 3869f47918f3..eb349ac7dd7b 100644 --- a/doc/manual/src/SUMMARY.md.in +++ b/doc/manual/src/SUMMARY.md.in @@ -36,6 +36,7 @@ - [Values](expressions/language-values.md) - [Language Constructs](expressions/language-constructs.md) - [Operators](expressions/language-operators.md) + - [Fetchers](expressions/fetchers.md) - [Derivations](expressions/derivations.md) - [Advanced Attributes](expressions/advanced-attributes.md) - [Built-in Constants](expressions/builtin-constants.md) diff --git a/doc/manual/src/expressions/advanced-attributes.md b/doc/manual/src/expressions/advanced-attributes.md index 000595815376..1515b239859f 100644 --- a/doc/manual/src/expressions/advanced-attributes.md +++ b/doc/manual/src/expressions/advanced-attributes.md @@ -207,13 +207,13 @@ Derivations can declare some infrequently used optional attributes. the hash in either hexadecimal or base-32 notation. (See the [`nix-hash` command](../command-ref/nix-hash.md) for information about converting to and from base-32 notation.) - + - `__contentAddressed` If this **experimental** attribute is set to true, then the derivation outputs will be stored in a content-addressed location rather than the traditional input-addressed one. This only has an effect if the `ca-derivation` experimental feature is enabled. - + Setting this attribute also requires setting `outputHashMode` and `outputHashAlgo` like for *fixed-output derivations* (see above). - `passAsFile`\ diff --git a/doc/manual/src/expressions/builtins-prefix.md b/doc/manual/src/expressions/builtins-prefix.md index 87127de2acda..b421d81a1ee4 100644 --- a/doc/manual/src/expressions/builtins-prefix.md +++ b/doc/manual/src/expressions/builtins-prefix.md @@ -14,3 +14,7 @@ For instance, `derivation` is also available as `builtins.derivation`. builtins.derivation attrs

derivation in described in its own section.

+
fetchTree args; + builtins.fetchTree args
+

fetchTree is described in + its own section.

diff --git a/doc/manual/src/expressions/fetchers.md b/doc/manual/src/expressions/fetchers.md new file mode 100644 index 000000000000..ecd9e8be72f2 --- /dev/null +++ b/doc/manual/src/expressions/fetchers.md @@ -0,0 +1,147 @@ +**Warning**: +This section is **experimental** and its interface is subject to change. + +# Fetchers + +Nix supports fetching source trees +from different locations +through the `fetchTree` builtin. + +Below we document the supported backends +and their configuration options. + +## Git + +Allows you to fetch a Git source tree (similar to a `git clone`). + +> **Note** +> +> The `.git/` folder won't be saved for reproducibility. + +Options: + +- `type` + + Must be equal to `"git"`. +- `url` + + Location of the git repository as accepted by `git` + (i.e. a local path, http(s) or SSH URL). +- `ref` + + The git ref to look for the requested revision under. + This is often a branch or tag name. + Defaults to `HEAD`. + + If `ref` does not start with `refs/`, it will be prefixed with `refs/heads/`. +- `rev` + + The git revision to fetch. Defaults to the tip of `ref`. +- `submodules` + + A Boolean parameter that specifies + whether submodules should be checked out. + Defaults to `false`. +- `shallow` + + If `true` only the HEAD commit will be fetched. + Defaults to `true`. +- `allRefs` + + Whether to fetch all refs of the repository. + + With this argument being true, + it's possible to load a `rev` from *any* `ref` + (by default only `rev`s from the specified `ref` are supported). + Defaults to `false`. + + +Examples: + +- To fetch a private repository over SSH: + + ```nix + builtins.fetchTree { + type = "git"; + url = "git@github.com:my-secret/repo.git"; + ref = "main"; + rev = "2aeb84a3aac9bba4f9b7aa8731d35f3d6925b40f"; + } + ``` + +- To fetch an arbitrary reference: + + ```nix + builtins.fetchTree { + type = "git"; + url = "https://github.com/NixOS/nix.git"; + ref = "refs/heads/0.5-release"; + } + ``` + +- If the revision you're looking for is in the default branch of + the git repository you don't strictly need to specify the branch + name in the `ref` attribute. + + However, if the revision you're looking for is in a future + branch for the non-default branch you will need to specify the + the `ref` attribute as well. + + ```nix + builtins.fetchTree { + type = "git"; + url = "https://github.com/nixos/nix.git"; + rev = "841fcbd04755c7a2865c51c1e2d3b045976b7452"; + ref = "1.11-maintenance"; + } + ``` + + > **Note** + > + > It is nice to always specify the branch which a revision + > belongs to. Without the branch being specified, the fetcher + > might fail if the default branch changes. Additionally, it can + > be confusing to try a commit from a non-default branch and see + > the fetch fail. If the branch is specified the fault is much + > more obvious. + +- If the revision you're looking for is in the default branch of + the git repository you may omit the `ref` attribute. + + ```nix + builtins.fetchTree { + type = "git"; + url = "https://github.com/nixos/nix.git"; + rev = "841fcbd04755c7a2865c51c1e2d3b045976b7452"; + } + ``` + +- To fetch a specific tag: + + ```nix + builtins.fetchTree { + type = "git"; + url = "https://github.com/nixos/nix.git"; + ref = "refs/tags/1.9"; + } + ``` + +- To fetch the latest version of a remote branch: + + ```nix + builtins.fetchTree { + type = "git"; + url = "ssh://git@github.com/nixos/nix.git"; + ref = "master"; + } + ``` + + > **Note** + > + > Nix will refetch the branch in accordance with + > the option `tarball-ttl`. + + > **Note** + > + > Fetching the latest version of a remote branch + > is disabled in *Pure evaluation mode*.