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 1/2] 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 | 72 ++++++++++++++++++++-------
 1 file changed, 55 insertions(+), 17 deletions(-)

diff --git a/doc/build-helpers/fetchers.chapter.md b/doc/build-helpers/fetchers.chapter.md
index 21cadfaa21fa5..d37a2fecaccda 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 }:
-
-stdenv.mkDerivation {
-  name = "hello";
-  src = fetchgit {
-    url = "https://...";
-    sparseCheckout = [
-      "directory/to/be/included"
-      "another/directory"
-    ];
-    hash = "sha256-AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=";
-  };
-}
-```
+: Whether to also fetch the submodules of a repository.
+
+*`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}
 

From f5f7910797265ab5f7ae62f6aad0ad5b5ef648ff Mon Sep 17 00:00:00 2001
From: Atemu <git@atemu.net>
Date: Wed, 13 Nov 2024 15:16:47 +0100
Subject: [PATCH 2/2] fetchgit: nudge to update the manual when modifying
 parameters

Many parameters added over the past many years were not documented in the
manual. People likely simple didn't think to do that, so let's nudge them.

(cherry picked from commit ee97de3be97fe96c32489c60fa58c164eae2d0c9)
---
 pkgs/build-support/fetchgit/default.nix | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/pkgs/build-support/fetchgit/default.nix b/pkgs/build-support/fetchgit/default.nix
index 1b000fb49a99e..4c40cbcef7e16 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