From 1444ac86d1861cd5f5c6f14bae90bbf8c32b8b25 Mon Sep 17 00:00:00 2001
From: Atemu <git@atemu.net>
Date: Wed, 13 Nov 2024 15:08:45 +0100
Subject: [PATCH] doc: document commonly used fetchgit flags

Some important ones like fetchLFS were missing. See
https://discourse.nixos.org/t/how-to-use-git-lfs-with-fetchgit/55975 for a
documented instance where this confused a user.

This still isn't complete but the remaining ones I felt were rather niche and I
am not familiar enough with them to sufficiently document their purpose or
usage.

(cherry picked from commit 1712d71ea76c317a841d0f1308c8236fc43dee0a)
---
 doc/build-helpers/fetchers.chapter.md | 70 +++++++++++++++++++++------
 1 file changed, 54 insertions(+), 16 deletions(-)

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}