diff --git a/doc/build-helpers/fetchers.chapter.md b/doc/build-helpers/fetchers.chapter.md index 21cadfaa21fa..d37a2fecaccd 100644 --- a/doc/build-helpers/fetchers.chapter.md +++ b/doc/build-helpers/fetchers.chapter.md @@ -755,25 +755,63 @@ Used with Subversion. Expects `url` to a Subversion directory, `rev`, and `hash` Used with Git. Expects `url` to a Git repo, `rev`, and `hash`. `rev` in this case can be full the git commit id (SHA1 hash) or a tag name like `refs/tags/v1.0`. -Additionally, the following optional arguments can be given: `fetchSubmodules = true` makes `fetchgit` also fetch the submodules of a repository. If `deepClone` is set to true, the entire repository is cloned as opposing to just creating a shallow clone. `deepClone = true` also implies `leaveDotGit = true` which means that the `.git` directory of the clone won't be removed after checkout. +Additionally, the following optional arguments can be given: -If only parts of the repository are needed, `sparseCheckout` can be used. This will prevent git from fetching unnecessary blobs from server, see [git sparse-checkout](https://git-scm.com/docs/git-sparse-checkout) for more information: +*`fetchSubmodules`* (Boolean) -```nix -{ stdenv, fetchgit }: +: Whether to also fetch the submodules of a repository. -stdenv.mkDerivation { - name = "hello"; - src = fetchgit { - url = "https://..."; - sparseCheckout = [ - "directory/to/be/included" - "another/directory" - ]; - hash = "sha256-AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA="; - }; -} -``` +*`fetchLFS`* (Boolean) + +: Whether to fetch LFS objects. + +*`postFetch`* (String) + +: Shell code executed after the file has been fetched successfully. + This can do things like check or transform the file. + +*`leaveDotGit`* (Boolean) + +: Whether the `.git` directory of the clone should *not* be removed after checkout. + + Be warned though that the git repository format is not stable and this flag is therefore not suitable for actual use by itself. + Only use this for testing purposes or in conjunction with removing the `.git` directory in `postFetch`. + +*`deepClone`* (Boolean) + +: Clone the entire repository as opposing to just creating a shallow clone. + This implies `leaveDotGit`. + +*`sparseCheckout`* (List of String) + +: Prevent git from fetching unnecessary blobs from server. + This is useful if only parts of the repository are needed. + + ::: {.example #ex-fetchgit-sparseCheckout} + + # Use `sparseCheckout` to only include some directories: + + ```nix + { stdenv, fetchgit }: + + stdenv.mkDerivation { + name = "hello"; + src = fetchgit { + url = "https://..."; + sparseCheckout = [ + "directory/to/be/included" + "another/directory" + ]; + hash = "sha256-AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA="; + }; + } + ``` + ::: + + See [git sparse-checkout](https://git-scm.com/docs/git-sparse-checkout) for more information. + +Some additional parameters for niche use-cases can be found listed in the function parameters in the declaration of `fetchgit`: `pkgs/build-support/fetchgit/default.nix`. +Future parameters additions might also happen without immediately being documented here. ## `fetchfossil` {#fetchfossil} diff --git a/pkgs/build-support/fetchgit/default.nix b/pkgs/build-support/fetchgit/default.nix index 1b000fb49a99..4c40cbcef7e1 100644 --- a/pkgs/build-support/fetchgit/default.nix +++ b/pkgs/build-support/fetchgit/default.nix @@ -11,6 +11,8 @@ in "${if matched == null then base else builtins.head matched}${appendShort}"; in lib.makeOverridable (lib.fetchers.withNormalizedHash { } ( +# NOTE Please document parameter additions or changes in +# doc/build-helpers/fetchers.chapter.md { url, rev ? "HEAD", leaveDotGit ? deepClone , outputHash ? lib.fakeHash, outputHashAlgo ? null , fetchSubmodules ? true, deepClone ? false