doc: document commonly used fetchgit flags

[Atemu]

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 the to sufficiently document their purpose or usage.

Things done

• Built on platform(s)
  • x86_64-linux
  • aarch64-linux
  • x86_64-darwin
  • aarch64-darwin
• For non-Linux: Is sandboxing enabled in nix.conf? (See Nix manual)
  • sandbox = relaxed
  • sandbox = true
• Tested, as applicable:
  • NixOS test(s) (look inside nixos/tests)
  • and/or package tests
  • or, for functions and "core" functionality, tests in lib/tests or pkgs/test
  • made sure NixOS tests are linked to the relevant packages
• Tested compilation of all packages that depend on this change using nix-shell -p nixpkgs-review --run "nixpkgs-review rev HEAD". Note: all changes have to be committed, also see nixpkgs-review usage
• Tested basic functionality of all binary files (usually in ./result/bin/)
• 24.11 Release Notes (or backporting 23.11 and 24.05 Release notes)
  • (Package updates) Added a release notes entry if the change is major or breaking
  • (Module updates) Added a release notes entry if the change is significant
  • (Module addition) Added a release notes entry if adding a new NixOS module
• Fits CONTRIBUTING.md.

---

Add a 👍 reaction to pull requests you find important.

[nixos-discourse]

This pull request has been mentioned on NixOS Discourse. There might be relevant details there:

https://discourse.nixos.org/t/how-to-use-git-lfs-with-fetchgit/55975/3

[Atemu]

This looks a lot nicer now, thanks!

fetchgit

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 (Boolean)

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 268. Use sparseCheckout to only include some directories:

{ stdenv, fetchgit }:
stdenv.mkDerivation {

name = "hello";

src = fetchgit {

url = "https://...";

sparseCheckout = [

"directory/to/be/included"

"another/directory"

];

hash = "sha256-AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=";

};

}

See 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.

(The example is formatted properly in the actual manual.)

[Atemu]

Backporting because this is an improvement without possibility of any breakage and because it's required for this which should also be backported: #355973

[malikwirin]

I was the confused user.
This PR would have saved me some hours if it was already merged

[github-actions]

Backport failed for release-24.05, because it was unable to cherry-pick the commit(s).

Please cherry-pick the changes locally and resolve any conflicts.

git fetch origin release-24.05
git worktree add -d .worktree/backport-355685-to-release-24.05 origin/release-24.05
cd .worktree/backport-355685-to-release-24.05
git switch --create backport-355685-to-release-24.05
git cherry-pick -x 1712d71ea76c317a841d0f1308c8236fc43dee0a ee97de3be97fe96c32489c60fa58c164eae2d0c9

[github-actions]

Successfully created backport PR for release-24.11:

• [Backport release-24.11] doc: document commonly used fetchgit flags #356759

[gador]

This seems to break the manual:

nixos_render_docs.redirects.RedirectsError:
Identifiers present in the source must have a mapping in the redirects file.
    - ex-fetchgit-sparseCheckout

    This can happen when an identifier was added or renamed.
    Please update doc/redirects.json or nixos/doc/manual/redirects.json!

NOTE: If your Manual build passes locally and you see this message in CI, you probably need a rebase.

[gador]

Probably due to #353513 and can be fixed with

diff --git a/doc/redirects.json b/doc/redirects.json
index de640eed00c1..a5a876961848 100644
--- a/doc/redirects.json
+++ b/doc/redirects.json
@@ -1274,6 +1274,9 @@
   "fetchgit": [
     "index.html#fetchgit"
   ],
+  "ex-fetchgit-sparseCheckout": [
+    "index.html#ex-fetchgit-sparseCheckout"
+  ],
   "fetchfossil": [
     "index.html#fetchfossil"
   ],

[fricklerhandwerk]

@gador yes, thanks for your patience. @GetPsyched will soon add a helper command so we don't have to do these things manually.

[Atemu]

Thanks for the fix @gador.

@fricklerhandwerk @GetPsyched I was not aware that you'd need to do this. You should probably announce the fact that you must do this in the breaking changes for unstable thread.

[Atemu]

Thinking about this again, I don't think it was necessary to backport this for #355973 because this is just docs whereas the actual important thing for backports is the functionality.

It doesn't hurt to have this aswell as the docs in 24.11 but I won't backport to 24.05.

[GetPsyched]

@fricklerhandwerk @GetPsyched I was not aware that you'd need to do this. You should probably announce the fact that you must do this in the breaking changes for unstable thread.

I'm unsure how is this a breaking change. The CI will fail if the redirects aren't correct; it didn't fail for this PR simply because the CI on this PR ran before the redirects system was merged into master.

[Atemu]

I see. Though I think that's all the more reason to announce this as that'd allow those who might be caught by this caveat to notice it in their PRs.

If I knew of this change and that there was the possibility of an integration hazard like this, I'd have checked.