From 971b5cd58520d50756db54fe3a43286025d4ea08 Mon Sep 17 00:00:00 2001 From: Kevin Amado Date: Sun, 14 Nov 2021 02:55:46 -0500 Subject: [PATCH] fetchTree: add documentation - Since this section is going to be long due to the need of documenting the different backends then giving it its own section seems reasonable. Additionally, by introducing fetchers before derivations and after the basics of the language, it guides the lector through the mental model that in Nix you build your derivations from the data you fetch in a reproducible way in the first place - Start by documenting the `git` backend and then I'll be adding more --- doc/manual/src/SUMMARY.md.in | 1 + .../src/expressions/advanced-attributes.md | 4 +- doc/manual/src/expressions/builtins-prefix.md | 4 + doc/manual/src/expressions/fetchers.md | 147 ++++++++++++++++++ 4 files changed, 154 insertions(+), 2 deletions(-) create mode 100644 doc/manual/src/expressions/fetchers.md 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*.