Support sparse checkout for package subdirectories

[ahmet-cetinkaya]

Problem

NUR supports selecting a package entry point below a repository root via the file field, for example:

{
  "repos": {
    "example": {
      "url": "https://github.com/example/dotfiles",
      "file": "nixos/pkgs/nur.nix"
    }
  }
}

This controls evaluation, but NUR still fetches the entire Git repository. For monorepos such as dotfiles repositories, that can pull unrelated configuration, history, and large files even though only one package subtree is needed.

Proposed solution

Add an optional manifest field such as dir / subdirectory that limits the fetched checkout to a repository-relative directory (for example through Git sparse checkout, where supported). NUR could then evaluate default.nix within that directory, or resolve file relative to it.

Example:

{
  "repos": {
    "example": {
      "url": "https://github.com/example/dotfiles",
      "dir": "nixos/pkgs",
      "file": "nur.nix"
    }
  }
}

If sparse checkout is not feasible for the current fetch/update implementation, documenting that file changes only the evaluation entry point—not the fetched repository—and recommending a dedicated package repository would still make this constraint clearer.

Related: #133

[Pandapip1]

For GitHub specifically, IIRC we fetch the entire repository tarball rather than doing a git clone because this is appreciably faster. This is reasonable to implement for non-specially fetched repos though.

[ahmet-cetinkaya]

Good point re: GitHub archives already avoiding a full git clone — that part of my original concern doesn't really apply there.

One thing worth separating out though: sparse checkout wouldn't reduce download size for the GitHub/GitLab path anyway, since the archive/{rev}.zip / archive.tar.gz endpoints don't support fetching a path prefix — the whole tarball has to be downloaded regardless. So sparse checkout only makes sense for the fetchgit fallback path (non-GitHub/GitLab hosts), where nixpkgs' fetchgit already supports sparseCheckoutPatterns.

For the tarball path, a cheaper win would be trimming after fetch instead: once fetchzip extracts the archive, add a small derivation that copies out just attr.dir into the final store path, e.g.

src = if attr ? dir
  then pkgs.runCommand "${name}-src" { } ''
    cp -r ${fetched}/${attr.dir} $out
  ''
  else fetched;

This doesn't reduce the download, but it does keep unrelated files (config, assets, etc. living alongside the package subtree in a monorepo) out of the final derivation's closure — cheap (one extra cp, no new dependency), and doesn't touch the existing fetchzip/fetchgit selection logic.

Happy to put together a PR for this (dir field + post-fetch trim for the tarball path, sparse checkout for the fetchgit path) if that split sounds reasonable.