fetchgit: make sparseCheckout a list of strings

The `sparseCheckout` argument allows the user to specify directories or
patterns of files, which Git uses to filter files it should check-out.

Git expects a multi-line string on stdin ("newline-delimited list", see
`git-sparse-checkout(1)`), but within nixpkgs it is more consistent to
use a list of strings instead. The list elements are joined to a
multi-line string only before passing it to the builder script.

A deprecation warning is emitted if a (multi-line) string is passed to
`sparseCheckout`, but for the time being it is still accepted.

5 files changed, 34 insertions, 15 deletions

diff --git a/doc/builders/fetchers.chapter.md b/doc/builders/fetchers.chapter.md
index 12d8a5d887f..43aead0ad5e 100644
--- a/doc/builders/fetchers.chapter.md
+++ b/doc/builders/fetchers.chapter.md
@@ -100,10 +100,10 @@ stdenv.mkDerivation {
   name = "hello";
   src = fetchgit {
     url = "https://...";
-    sparseCheckout = ''
-      directory/to/be/included
-      another/directory
-    '';
+    sparseCheckout = [
+      "directory/to/be/included"
+      "another/directory"
+    ];
     sha256 = "0000000000000000000000000000000000000000000000000000";
   };
 }
diff --git a/nixos/doc/manual/from_md/release-notes/rl-2211.section.xml b/nixos/doc/manual/from_md/release-notes/rl-2211.section.xml
index a2f67d2707e..b5381ccb472 100644
--- a/nixos/doc/manual/from_md/release-notes/rl-2211.section.xml
+++ b/nixos/doc/manual/from_md/release-notes/rl-2211.section.xml
@@ -545,6 +545,15 @@
       </listitem>
       <listitem>
         <para>
+          The <literal>fetchgit</literal> fetcher supports sparse
+          checkouts via the <literal>sparseCheckout</literal> option.
+          This used to accept a multi-line string with
+          directories/patterns to check out, but now requires a list of
+          strings.
+        </para>
+      </listitem>
+      <listitem>
+        <para>
           <literal>openssh</literal> was updated to version 9.1,
           disabling the generation of DSA keys when using
           <literal>ssh-keygen -A</literal> as they are insecure. Also,
diff --git a/nixos/doc/manual/release-notes/rl-2211.section.md b/nixos/doc/manual/release-notes/rl-2211.section.md
index 3540881c462..913b3f9aea1 100644
--- a/nixos/doc/manual/release-notes/rl-2211.section.md
+++ b/nixos/doc/manual/release-notes/rl-2211.section.md
@@ -179,6 +179,8 @@ Available as [services.patroni](options.html#opt-services.patroni.enable).
 
 - The `fetchgit` fetcher now uses [cone mode](https://www.git-scm.com/docs/git-sparse-checkout/2.37.0#_internalscone_mode_handling) by default for sparse checkouts. [Non-cone mode](https://www.git-scm.com/docs/git-sparse-checkout/2.37.0#_internalsnon_cone_problems) can be enabled by passing `nonConeMode = true`, but note that non-cone mode is deprecated and this option may be removed alongside a future Git update without notice.
 
+- The `fetchgit` fetcher supports sparse checkouts via the `sparseCheckout` option. This used to accept a multi-line string with directories/patterns to check out, but now requires a list of strings.
+
 - `openssh` was updated to version 9.1, disabling the generation of DSA keys when using `ssh-keygen -A` as they are insecure. Also, `SetEnv` directives in `ssh_config` and `sshd_config` are now first-match-wins
 
 - `bsp-layout` no longer uses the command `cycle` to switch to other window layouts, as it got replaced by the commands `previous` and `next`.
diff --git a/pkgs/build-support/fetchgit/default.nix b/pkgs/build-support/fetchgit/default.nix
index f516c3d5a03..1fec0c88747 100644
--- a/pkgs/build-support/fetchgit/default.nix
+++ b/pkgs/build-support/fetchgit/default.nix
@@ -15,7 +15,7 @@ in
 { url, rev ? "HEAD", md5 ? "", sha256 ? "", hash ? "", leaveDotGit ? deepClone
 , fetchSubmodules ? true, deepClone ? false
 , branchName ? null
-, sparseCheckout ? ""
+, sparseCheckout ? []
 , nonConeMode ? false
 , name ? urlToName url rev
 , # Shell code executed after the file has been fetched
@@ -55,13 +55,16 @@ in
 */
 
 assert deepClone -> leaveDotGit;
-assert nonConeMode -> (sparseCheckout != "");
+assert nonConeMode -> !(sparseCheckout == "" || sparseCheckout == []);
 
 if md5 != "" then
   throw "fetchgit does not support md5 anymore, please use sha256"
 else if hash != "" && sha256 != "" then
   throw "Only one of sha256 or hash can be set"
 else
+# Added 2022-11-12
+lib.warnIf (builtins.isString sparseCheckout)
+  "Please provide directories/patterns for sparse checkout as a list of strings. Support for passing a (multi-line) string is deprecated and will be removed in the next release."
 stdenvNoCC.mkDerivation {
   inherit name;
   builder = ./builder.sh;
@@ -79,7 +82,12 @@ stdenvNoCC.mkDerivation {
   else
     lib.fakeSha256;
 
-  inherit url rev leaveDotGit fetchLFS fetchSubmodules deepClone branchName sparseCheckout nonConeMode postFetch;
+  # git-sparse-checkout(1) says:
+  # > When the --stdin option is provided, the directories or patterns are read
+  # > from standard in as a newline-delimited list instead of from the arguments.
+  sparseCheckout = if builtins.isString sparseCheckout then sparseCheckout else builtins.concatStringsSep "\n" sparseCheckout;
+
+  inherit url rev leaveDotGit fetchLFS fetchSubmodules deepClone branchName nonConeMode postFetch;
 
   postHook = if netrcPhase == null then null else ''
     ${netrcPhase}
diff --git a/pkgs/build-support/fetchgit/tests.nix b/pkgs/build-support/fetchgit/tests.nix
index 62fe3f77bbd..a18be65327b 100644
--- a/pkgs/build-support/fetchgit/tests.nix
+++ b/pkgs/build-support/fetchgit/tests.nix
@@ -12,10 +12,10 @@
     name = "nix-source";
     url = "https://github.com/NixOS/nix";
     rev = "9d9dbe6ed05854e03811c361a3380e09183f4f4a";
-    sparseCheckout = ''
-      src
-      tests
-    '';
+    sparseCheckout = [
+      "src"
+      "tests"
+    ];
     sha256 = "sha256-g1PHGTWgAcd/+sXHo1o6AjVWCvC6HiocOfMbMh873LQ=";
   };
 
@@ -23,10 +23,10 @@
     name = "nix-source";
     url = "https://github.com/NixOS/nix";
     rev = "9d9dbe6ed05854e03811c361a3380e09183f4f4a";
-    sparseCheckout = ''
-      src
-      tests
-    '';
+    sparseCheckout = [
+      "src"
+      "tests"
+    ];
     nonConeMode = true;
     sha256 = "sha256-FknO6C/PSnMPfhUqObD4vsW4PhkwdmPa9blNzcNvJQ4=";
   };