doc: document commonly used fetchgit flags (#355685)

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
+: Whether to also fetch the submodules of a repository.
-{ stdenv, fetchgit }:
 
-stdenv.mkDerivation {
+*`fetchLFS`* (Boolean)
-  name = "hello";
+
-  src = fetchgit {
+: Whether to fetch LFS objects.
-    url = "https://...";
+
-    sparseCheckout = [
+*`postFetch`* (String)
-      "directory/to/be/included"
+
-      "another/directory"
+: Shell code executed after the file has been fetched successfully.
-    ];
+  This can do things like check or transform the file.
-    hash = "sha256-AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=";
+
-  };
+*`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}
 

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