qbit/nixpkgs
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

doc: document commonly used fetchgit flags

Browse Source 
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.
This commit is contained in:
Atemu 2024-11-13 15:08:45 +01:00
parent 76612b17c0
commit 1712d71ea7
1 changed files with 54 additions and 16 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

70
doc/build-helpers/fetchers.chapter.md
View File

@ -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`. 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} ## `fetchfossil` {#fetchfossil}