git-lfs support

[b-camacho]

Motivation

nix fetches git repos using libgit2, which does not run filters by default. This means LFS-enabled repos can be fetched, but LFS pointer files are not smudged.

This change adds a lfs attribute to fetcher URLs. With lfs=1, when fetching LFS-enabled repos, nix will smudge all the files.

Context

See #10079.
Git Large File Storage lets you track large files directly in git, using git filters. A clean filter runs on your LFS-enrolled files before push, replacing large files with small "pointer files". Upon checkout, a "smudge" filter replaces pointer files with full file contents. When this works correctly, it is not visible to users, which is nice.

Changes

• builtins.fetchGit has new bool lfs attr
• when lfs=true, GitSourceAccessor will smudge any pointer files with the lfs filter attribute
• as verified by new test in tests/nixos/fetchgit (this is why lfs is now enabled on the test gitea instance)

Priorities and Process

Add 👍 to pull requests you find important.

The Nix maintainer team uses a GitHub project board to schedule and track reviews.

[b-camacho]

Small complication:
it seems that nix flake lock calls fetch which in turn calls Input::fetch -> InputScheme::fetch -> fetchToStore.

In other words, I don't currently see a way to:

• materialize LFS files when fetching -source store paths, but
• don't materialize LFS files during nix flake lock.

[L-as]

What use case do you have in mind? Isn't LFS typically for large files, that wouldn't usually affect evaluation anyway?

[b-camacho]

What use case do you have in mind? Isn't LFS typically for large files, that wouldn't usually affect evaluation anyway?

builtins.fetchGit populates the nix store with a <hash>-store path. This path is used as the source when building a derivation. Currently, the builder will see the unsmudged LFS pointer files, but I'd like the builder to optionally see smudged files. I agree that smudged files are usually not needed at eval time, but I don't see a good alternative of making them available at build time, besides a fixed-output derivation (but fixed-output derivations have their own problems)

[L-as]

A FOD seems optimal here, in general you shouldn't use builtins.fetchGit if you're only going to use it at build time.

[b-camacho]

In general I agree, but (afaik) other fetchers can't use git credentials.

[nixos-discourse]

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

https://discourse.nixos.org/t/2024-03-11-nix-team-meeting-132/42960/1

[khoitd1997]

@roberth have you had a chance to take a look at this issue? We have been staying at older versions of Nix as a workaround but newer versions now have fixes for critical issues so sticking to old ones would no longer be optimal.

[roberth]

Hi @b-camacho, thanks for the ping and sorry for the delay. This PR was assigned to me, but I hadn't prioritized it because it was a draft. Wrong assumption on my end, because I do think this is valuable, and I have some things to say :)

when fetching LFS-enabled repos, nix will smudge all the files.

That's a good start, but we need to make sure that the smudging happens in a controlled manner; otherwise we risk adding impurities.

Specifically, we should parse the attribute to check that they're supposed to be unsmudged by lfs; if not, ignore the smudge rule. It seems you were already investigating how this could be implemented.

Furthermore, we should validate the sha256 so that we don't increase the potential for silent errors by a whole external program. The hash should be easy to parse from the pointer file, and while reading other programs' inputs is a little ad hoc, I don't expect any serious issues from this, as we won't cause users to accidentally rely on a bug this way.

---

the LFS-tracked files are materialized during nix flake lock - this is bad

This won't happen unnecessarily either of these are implemented

• Lazy trees #6530
• Lazy fetchTree outPath path values #10252

If we need to backtrack on the removal of narHashes (#6530), we can also avoid re-locking transitive inputs whose lock has already been computed by the dependency's lock.

• Reuse input lock files #7730

So yes, this isn't efficient yet, but it will be.

A FOD seems optimal here, in general you shouldn't use builtins.fetchGit if you're only going to use it at build time.

A fixed output derivation works best when all you're using it for is as an input to another derivation (and it's publicly available, as mentioned).
However, if the "fetched" source is a flake (e.g. you have a flake.nix in a repo with LFS files), then you also need to evaluate files from the fetched source, which would constitute import from derivation, which is not optimal. Furthermore you'd need to produce fixed-output hashes for your local repo files, which is such horrible UX we don't need to consider it as a solution.

---

To summarize, this is worth implementing, I see no blocking issues, design or otherwise, and the following needs to be done:

• lfs attribute with default false, LGTM
• figure out which files are LFS
• invoke the Git LFS filter from $PATH; no need for a rigid dependency or makeWrapper
• check the sha256
• add a test, perhaps extending tests/nixos/fetch-git
• documentation for the lfs attribute (currently under fetchGit's entry in doc/manual/src/language/builtins.md); mention the runtime dependency on the LFS package.

[kip93]

What's the state on this PR? Seems to unfortunately be a bit stale given the delayed review. This issue has been plaguing us for a while, so I'm willing to pick up the torch here and try to get this out the door (was actually starting to see how to fix this myself back in March when I saw this PR and decided to see what came out of this).

[roberth]

@kip93 I think your question was directed towards @b-camacho, but I'd like to add that we would welcome and support anyone who'd like to work on this.

Feel free to ask questions here or in the meetings if you can make them. We generally have some agenda, but we also like to make time for contributors during or after, when we often hang out while we get some things done. Link to the video conference is in the scratchpad linked there. We also have a matrix room, although personally I'm guilty of neglecting that one sometimes.

[b-camacho]

Thanks for the thorough writeup @roberth !
I owe you all an update. To avoid shelling out and implement some features we need to merge, I need a subset of a git-lft C/C++ client. I reimplemented one from Python into C++ here https://github.com/b-camacho/git-lfs-fetch-cpp.

Once I add some tests and integrate git-lfs-fetch-cpp here, we should be ready for another review!

I'm still on vacation with not-great internet, but back in 6 days and will update you all on 7/31 regardless.

Thanks for the feedback and sorry for the wait!

[roberth]

Oh, I don't think shelling out was such a big deal because we can verify the correctness of the result, kind of like how fixed output derivations are allowed to do "grossly impure" things because we can verify the output.

I guess a library implementation of it is still nice for a consistent UX with a small closure size though.

[kip93]

Hey! It's me again! I just want to ask if there's anything I can help with here. Maybe I can try and doing some testing, or do a smaller version of this that uses the git-lfs CLI tools while the full implementation gets done?

We have a lot of repos with LFS files that would greatly benefit from this, so I'm willing to do whatever work is needed, but also don't want to add extra work for others where it's not wanted.

[b-camacho]

Except a URL parsing quirk I think it's ready!
Added an e2e test and fixed some parsing, will be back tomorrow to touch it up.
Currently the filter attribute matching still uses my homebrew pathspec impl, I also need to replace that with https://libgit2.org/libgit2/#HEAD/group/pathspec/git_pathspec_matches_path

[kip93]

Seems like when you went and asked for help I could not do so and now almost everything seems to be done. It looks to me the least I can do is throw this at our repos with a variety of lfs files to see if at least I can help test that it works as expected. Looking at the nixos tests I can think of an edge case or 2 that usually git just throws warnings about, and I'm not sure how this implementation would deal with those.

[b-camacho]

Seems like when you went and asked for help I could not do so and now almost everything seems to be done

that's on me, I should have been more responsive when you first offered!

least I can do is throw this at our repos with a variety of lfs files

that would be wonderful, but there is another mystery I would really like your help with @kip93! it seems something is wrong with path caching, but only in nixos tests.

when nix decides whether to fetch a store path or use a cached one, it uses a cache key that looks like this

        cacheKey = fetchers::Cache::Key{"fetchToStore", {
            {"name", std::string{name}},
            {"fingerprint", *path.accessor->fingerprint},
            {"method", std::string{method.render()}},
            {"path", path.path.abs()}
        }};

that fingerprint is what interests us - for git that's the repo rev + attributes like "useSubmodules" or "export-ignore" (and now also lfs). to get the new fingerprint, we simply optionally append ";l" to it when "lfs = true". this part works fine on my machine and in nixos tests.

however, in nixos tests we compute the same store path whether the ";l" suffix is there or not. You can verify this on your machine, pull latest of this branch and run nix build --impure '.#hydraJobs.tests.fetch-git' - I left in some debug prints proving the fingerprints are different. conversely, if you'd like to verify that the paths are different outside of the test, you can run

./outputs/out/bin/nix --extra-experimental-features nix-command eval --impure --raw --expr '(
      builtins.fetchGit {
        url = "[email protected]:b-camacho/test-lfs.git";
        rev = "5536a6ce88a520ab059a04c8249cbe1f9295f7cc";
        ref = "main";
        lfs = true;
      }
    ).outPath'
./outputs/out/bin/nix --extra-experimental-features nix-command eval --impure --raw --expr '(
      builtins.fetchGit {
        url = "[email protected]:b-camacho/test-lfs.git";
        rev = "5536a6ce88a520ab059a04c8249cbe1f9295f7cc";
        ref = "main";
        lfs = false;
      }
    ).outPath'

and observe the paths are different.

I don't know why two different fingerprints seem to produce the same cache key, especially why it only happens in the test VM, I'd love your help investigating further (I would probably start by printing the cache key?). the relevant code uses ample inheritance of implementation so it's a little hard to understand for me. Ofc if you're too busy (or would rather not look into this for any reason) lmk and I'll keep trying.

[kip93]

Interesting, I'll certainly have a look and let you know what I find out

[kip93]

Ok, just as an update of my progress (or lack thereof) so far:

• Took a while to parse through the code and try to understand the flow.
• Tried to get the cache key using std::cerr << "nix::fetchToStore cacheKey:" << fetchers::attrsToJSON(cacheKey.value().second) << std::endl; but it looks ok ({"fingerprint":"8602f7662e242b18d27fdc830150e51d4fb5051b;e","method":"nar","name":"source","path":"/"} vs {"fingerprint":"8602f7662e242b18d27fdc830150e51d4fb5051b;e;l","method":"nar","name":"source","path":"/"}).
• Disabled the cache code entirely, still gets the same path in both cases.
• Been going down the rabbit hole ever since, coming up with dead ends. :/
• My only suspect right now is the treeHashToNarHash function in git-utils, which assumes a NAR hash out of just a rev, but can't see where it's used and that would also fail outside of the VM? All around confusion.

Anyways, not don't have any more time this week to look at it, will try again next week

[b-camacho]

I got hopeful and went to check treeHashToNarHash but it doesn't get called when running in the VM, I'm equally stumped

[b-camacho]

Figured it out!
The storepath (ie the nix sha256) is not calculated from the fingerprint, but from contents. With --debug it actually says the cache missed

nix eval --debug --impure --raw --expr '(
      builtins.fetchGit {
        url = "http://gitea:3000/test/lfs";
        rev = "755514e46a902f778e4ea9a087e3cafb970c1810";
        ref = "main";
        lfs = true;
      }
    ).outPath'
evaluating file '<nix/derivation-internal.nix>'
locking path '/root/.cache/nix/gitv3/0iq989hd50hql2bp8bdpn06lddbhpd2fjl21xw9qw0drrr4l5yrr'
lock acquired on '/root/.cache/nix/gitv3/0iq989hd50hql2bp8bdpn06lddbhpd2fjl21xw9qw0drrr4l5yrr.lock'
lock released on '/root/.cache/nix/gitv3/0iq989hd50hql2bp8bdpn06lddbhpd2fjl21xw9qw0drrr4l5yrr.lock'
using cache entry 'gitLastModified:{"rev":"755514e46a902f778e4ea9a087e3cafb970c1810"}' -> '{"lastModified":1731733520}'
using cache entry 'gitRevCount:{"rev":"755514e46a902f778e4ea9a087e3cafb970c1810"}' -> '{"revCount":1}'
using revision 755514e46a902f778e4ea9a087e3cafb970c1810 of repo 'http://gitea:3000/test/lfs'
smudgeLfs: 1
getFingerprint: 755514e46a902f778e4ea9a087e3cafb970c1810;e;l
did not find cache entry for 'fetchToStore:{"fingerprint":"755514e46a902f778e4ea9a087e3cafb970c1810;e;l","method":"nar","name":"source","path":"/","store":"/nix/store"}'
copying '«git+http://gitea:3000/test/lfs?exportIgnore=1&ref=main&rev=755514e46a902f778e4ea9a087e3cafb970c1810»«unknown»/' to the store...
acquiring write lock on '/nix/var/nix/temproots/1317'
/nix/store/c5a3w5jsfsrh812gdvzljgg21ccnin3a-source

So why was it not smudging the file? Before smudging a pointer file we check if it has a filter=lfs attribute in .gitattributes. .gitattributes contains lines that look like this: *.big_ext filter=lfs..., that first part is the "pathspec" (=~glob pattern in libgit2 lingo). When I was checking if the pathspec matches the file path, I was using an absolute, instead of relative path and the leading / broke the pathspec matcher.

easy fix in retrospect! Thanks so much for your help running this down @kip93!

Separately, I cleaned up the patchspec matching code and added more tests.

I think we're ready for a review, lmk what else we need @roberth!

[kip93]

Nice! I did not look into the smudging logic itself, so figures I did not see that u.u

Anyway, then I'll proceed to do some manual testing (I think I can also add a new test or 2).

Also, while waiting for compilation here and there, I wrote some small docs that are probably necessary to add. Not sure if I can make a PR into a PR, but here's the commit in my own repo: b48dacd5

[kip93]

Just for visibility, I've already managed to break it with a not-so-much-edge-case 🙈

BUT, I'm already working on a fix, plus I already have a test in place to ensure it works as expected.

[b-camacho]

nice! I added you as collaborator on b-camacho:lfs, I think it'll let you push directly to this PR once you accept

[kip93]

Took me a bit longer than I expected (mostly because my C++ is lacking), but I believe I've fixed the issues I could see (mostly based around people can make mistakes, don't just assume everything will just work).

Still need to test this more thoroughly with our real world usage of lfs, but from weird cases that I've seen in the wild, I think I've covered those.

[b-camacho]

Tonight I'm gotta try fetchGiting a random selection of popular lfs-using repos:
https://github.com/Wasted-Audio/hvcc
https://github.com/ChainSafe/gossamer
https://github.com/ivy-llc/ivy
https://github.com/game-ci/unity-test-runner