feat: add LFS snapshot support to git strategy

docker/Dockerfile

@@ -6,7 +6,7 @@ ARG TARGETARCH
 SHELL ["/bin/sh", "-o", "pipefail", "-c"]
 
 # Install runtime dependencies for git operations and TLS
-RUN apk add --no-cache ca-certificates curl git git-daemon tzdata zstd && \
+RUN apk add --no-cache ca-certificates curl git git-daemon git-lfs tzdata zstd && \
     addgroup -g 1000 cachew && \
     adduser -D -u 1000 -G cachew cachew
 

internal/gitclone/command.go

@@ -11,7 +11,9 @@ import (
 	"github.com/alecthomas/errors"
 )
 
-func (r *Repository) gitCommand(ctx context.Context, args ...string) (*exec.Cmd, error) {
+// GitCommand returns a git subprocess configured with repository-scoped
+// authentication and any per-URL git config overrides disabled.
+func (r *Repository) GitCommand(ctx context.Context, args ...string) (*exec.Cmd, error) {
 	repoURL := r.upstreamURL
 	var token string
 	if r.credentialProvider != nil && strings.Contains(repoURL, "github.com") {

internal/gitclone/command_test.go

@@ -51,7 +51,7 @@ func TestGitCommand(t *testing.T) {
 		credentialProvider: nil,
 	}
 
-	cmd, err := repo.gitCommand(ctx, "version")
+	cmd, err := repo.GitCommand(ctx, "version")
 	assert.NoError(t, err)
 
 	assert.NotZero(t, cmd)
@@ -70,7 +70,7 @@ func TestGitCommandWithEmptyURL(t *testing.T) {
 		credentialProvider: nil,
 	}
 
-	cmd, err := repo.gitCommand(ctx, "version")
+	cmd, err := repo.GitCommand(ctx, "version")
 	assert.NoError(t, err)
 
 	assert.NotZero(t, cmd)
@@ -124,7 +124,7 @@ func TestGitCommandWithCredentialProvider(t *testing.T) {
 				},
 			}
 
-			cmd, err := repo.gitCommand(ctx, "version")
+			cmd, err := repo.GitCommand(ctx, "version")
 			assert.NoError(t, err)
 			assert.NotZero(t, cmd)
 

internal/gitclone/manager.go

@@ -504,7 +504,7 @@ func (r *Repository) executeClone(ctx context.Context) error {
 		r.upstreamURL, cloneDest,
 	}
 
-	cmd, err := r.gitCommand(cloneCtx, args...)
+	cmd, err := r.GitCommand(cloneCtx, args...)
 	if err != nil {
 		return errors.Wrap(err, "create git command")
 	}
@@ -582,8 +582,7 @@ func (r *Repository) fetchInternal(ctx context.Context, timeout time.Duration, e
 	}
 	args = append(args, "fetch", "--prune", "--prune-tags")
 
-	// #nosec G204 - r.path is controlled by us
-	cmd, err := r.gitCommand(fetchCtx, args...)
+	cmd, err := r.GitCommand(fetchCtx, args...)
 	if err != nil {
 		return errors.Wrap(err, "create git command")
 	}
@@ -681,7 +680,7 @@ func (r *Repository) GetLocalRefs(ctx context.Context) (map[string]string, error
 
 func (r *Repository) GetUpstreamRefs(ctx context.Context) (map[string]string, error) {
 	// #nosec G204 - r.upstreamURL is controlled by us
-	cmd, err := r.gitCommand(ctx, "ls-remote", r.upstreamURL)
+	cmd, err := r.GitCommand(ctx, "ls-remote", r.upstreamURL)
 	if err != nil {
 		return nil, errors.Wrap(err, "create git command")
 	}

internal/snapshot/snapshot.go

@@ -27,20 +27,42 @@ import (
 // Any extra headers are merged into the cache metadata alongside the default
 // Content-Type and Content-Disposition headers.
 func Create(ctx context.Context, remote cache.Cache, key cache.Key, directory string, ttl time.Duration, excludePatterns []string, threads int, extraHeaders ...http.Header) error {
+	return CreatePaths(ctx, remote, key, directory, filepath.Base(directory), []string{"."}, ttl, excludePatterns, threads, extraHeaders...)
+}
+
+// CreatePaths archives named paths within baseDir using tar with zstd compression,
+// then uploads the resulting archive to the cache.
+//
+// The archive preserves all file permissions, ownership, and symlinks.
+// Each entry in includePaths is archived relative to baseDir and must exist.
+// This allows callers to archive either an entire directory with "." or a
+// specific subtree such as "lfs" while preserving that relative path prefix.
+// Exclude patterns use tar's --exclude syntax.
+// threads controls zstd parallelism; 0 uses all available CPU cores.
+func CreatePaths(ctx context.Context, remote cache.Cache, key cache.Key, baseDir, archiveName string, includePaths []string, ttl time.Duration, excludePatterns []string, threads int, extraHeaders ...http.Header) error {
 	if threads <= 0 {
 		threads = runtime.NumCPU()
 	}
 
-	// Verify directory exists
-	if info, err := os.Stat(directory); err != nil {
-		return errors.Wrap(err, "failed to stat directory")
+	if len(includePaths) == 0 {
+		return errors.New("includePaths must not be empty")
+	}
+
+	if info, err := os.Stat(baseDir); err != nil {
+		return errors.Wrap(err, "failed to stat base directory")
 	} else if !info.IsDir() {
-		return errors.Errorf("not a directory: %s", directory)
+		return errors.Errorf("not a directory: %s", baseDir)
+	}
+	for _, path := range includePaths {
+		targetPath := filepath.Join(baseDir, path)
+		if _, err := os.Stat(targetPath); err != nil {
+			return errors.Wrapf(err, "failed to stat include path %q", path)
+		}
 	}
 
 	headers := make(http.Header)
 	headers.Set("Content-Type", "application/zstd")
-	headers.Set("Content-Disposition", fmt.Sprintf("attachment; filename=%q", filepath.Base(directory)+".tar.zst"))
+	headers.Set("Content-Disposition", fmt.Sprintf("attachment; filename=%q", archiveName+".tar.zst"))
 	for _, eh := range extraHeaders {
 		for k, vals := range eh {
 			for _, v := range vals {
@@ -54,12 +76,22 @@ func Create(ctx context.Context, remote cache.Cache, key cache.Key, directory st
 		return errors.Wrap(err, "failed to create object")
 	}
 
-	tarArgs := []string{"-cpf", "-", "-C", directory}
+	tarArgs := []string{"-cpf", "-", "-C", baseDir}
 	for _, pattern := range excludePatterns {
 		tarArgs = append(tarArgs, "--exclude", pattern)
 	}
-	tarArgs = append(tarArgs, ".")
+	tarArgs = append(tarArgs, "--")
+	tarArgs = append(tarArgs, includePaths...)
+
+	if err := runTarZstdPipeline(ctx, tarArgs, threads, wc); err != nil {
+		return errors.Join(err, wc.Close())
+	}
+	return errors.Wrap(wc.Close(), "failed to close writer")
+}
 
+// runTarZstdPipeline runs tar piped through zstd, writing compressed output to w.
+// The caller is responsible for closing w after this returns.
+func runTarZstdPipeline(ctx context.Context, tarArgs []string, threads int, w io.Writer) error {
 	tarCmd := exec.CommandContext(ctx, "tar", tarArgs...)
 	zstdCmd := exec.CommandContext(ctx, "zstd", "-c", fmt.Sprintf("-T%d", threads)) //nolint:gosec // threads is a validated integer, not user input
 
@@ -68,33 +100,32 @@ func Create(ctx context.Context, remote cache.Cache, key cache.Key, directory st
 	// closing the read end ensures tar receives SIGPIPE instead of blocking.
 	pr, pw, err := os.Pipe()
 	if err != nil {
-		return errors.Join(errors.Wrap(err, "failed to create pipe"), wc.Close())
+		return errors.Wrap(err, "failed to create pipe")
 	}
 
 	var tarStderr, zstdStderr bytes.Buffer
 	tarCmd.Stdout = pw
 	tarCmd.Stderr = &tarStderr
 
 	zstdCmd.Stdin = pr
-	zstdCmd.Stdout = wc
+	zstdCmd.Stdout = w
 	zstdCmd.Stderr = &zstdStderr
 
 	if err := tarCmd.Start(); err != nil {
 		pw.Close() //nolint:errcheck,gosec // best-effort cleanup
 		pr.Close() //nolint:errcheck,gosec // best-effort cleanup
-		return errors.Join(errors.Wrap(err, "failed to start tar"), wc.Close())
+		return errors.Wrap(err, "failed to start tar")
 	}
 	pw.Close() //nolint:errcheck,gosec // parent no longer needs write end; tar holds its own copy
 
 	if err := zstdCmd.Start(); err != nil {
 		pr.Close() //nolint:errcheck,gosec // let tar receive SIGPIPE so it exits
-		return errors.Join(errors.Wrap(err, "failed to start zstd"), tarCmd.Wait(), wc.Close())
+		return errors.Join(errors.Wrap(err, "failed to start zstd"), tarCmd.Wait())
 	}
 	pr.Close() //nolint:errcheck,gosec // parent no longer needs read end; if zstd dies, tar gets SIGPIPE
 
 	tarErr := tarCmd.Wait()
 	zstdErr := zstdCmd.Wait()
-	closeErr := wc.Close()
 
 	var errs []error
 	if tarErr != nil {
@@ -103,10 +134,6 @@ func Create(ctx context.Context, remote cache.Cache, key cache.Key, directory st
 	if zstdErr != nil {
 		errs = append(errs, errors.Errorf("zstd failed: %w: %s", zstdErr, zstdStderr.String()))
 	}
-	if closeErr != nil {
-		errs = append(errs, errors.Wrap(closeErr, "failed to close writer"))
-	}
-
 	return errors.Join(errs...)
 }
 

internal/strategy/git/git.go

@@ -38,9 +38,7 @@ type Config struct {
 	SnapshotInterval       time.Duration `hcl:"snapshot-interval,optional" help:"How often to generate tar.zstd workstation snapshots. 0 disables snapshots." default:"0"`
 	MirrorSnapshotInterval time.Duration `hcl:"mirror-snapshot-interval,optional" help:"How often to generate mirror snapshots for pod bootstrap. 0 uses snapshot-interval. Defaults to 2h." default:"2h"`
 	RepackInterval         time.Duration `hcl:"repack-interval,optional" help:"How often to run full repack. 0 disables." default:"0"`
-	// ServerURL is embedded as remote.origin.url in snapshots so git pull goes through cachew.
-	ServerURL   string `hcl:"server-url,optional" help:"Base URL of this cachew instance, embedded in snapshot remote URLs." default:"${CACHEW_URL}"`
-	ZstdThreads int    `hcl:"zstd-threads,optional" help:"Threads for zstd compression/decompression (0 = all CPU cores)." default:"0"`
+	ZstdThreads            int           `hcl:"zstd-threads,optional" help:"Threads for zstd compression/decompression (0 = all CPU cores)." default:"0"`
 }
 
 type Strategy struct {
@@ -83,6 +81,10 @@ func New(
 
 	logger := logging.FromContext(ctx)
 
+	if _, err := exec.LookPath("git-lfs"); err != nil {
+		return nil, errors.New("git-lfs is required but not found in PATH")
+	}
+
 	// Get GitHub App token manager if configured
 	tokenManager, err := tokenManagerProvider()
 	if err != nil {
@@ -122,8 +124,6 @@ func New(
 		tokenManager: tokenManager,
 		metrics:      m,
 	}
-	s.config.ServerURL = strings.TrimRight(config.ServerURL, "/")
-
 	if err := s.warmExistingRepos(ctx); err != nil {
 		logger.WarnContext(ctx, "Failed to warm existing repos", "error", err)
 	}
@@ -199,6 +199,7 @@ func (s *Strategy) warmExistingRepos(ctx context.Context) error {
 
 		if s.config.SnapshotInterval > 0 {
 			s.scheduleSnapshotJobs(repo)
+			s.scheduleLFSSnapshotJobs(repo)
 		}
 		if s.config.RepackInterval > 0 {
 			s.scheduleRepackJobs(repo)
@@ -237,6 +238,22 @@ func (s *Strategy) handleRequest(w http.ResponseWriter, r *http.Request) {
 		return
 	}
 
+	if strings.HasSuffix(pathValue, "/lfs-snapshot.tar.zst") {
+		s.metrics.recordRequest(ctx, "lfs-snapshot")
+		s.handleLFSSnapshotRequest(w, r, host, pathValue)
+		return
+	}
+
+	// Proxy LFS Batch API requests directly to GitHub. Cachew doesn't cache
+	// individual LFS objects, but it needs to handle these requests because
+	// git's url.*.insteadOf rewrites the LFS endpoint URL to point at cachew.
+	if strings.Contains(pathValue, "/info/lfs/") {
+		s.metrics.recordRequest(ctx, "lfs-api")
+		logger.DebugContext(ctx, "Proxying LFS API request to upstream", "uri", pathValue)
+		s.forwardToUpstream(w, r, host, pathValue)
+		return
+	}
+
 	service := r.URL.Query().Get("service")
 	isReceivePack := service == "git-receive-pack" || strings.HasSuffix(pathValue, "/git-receive-pack")
 
@@ -248,6 +265,12 @@ func (s *Strategy) handleRequest(w http.ResponseWriter, r *http.Request) {
 	}
 
 	s.metrics.recordRequest(ctx, "upload-pack")
+	s.handleGitRequest(w, r, host, pathValue)
+}
+
+func (s *Strategy) handleGitRequest(w http.ResponseWriter, r *http.Request, host, pathValue string) {
+	ctx := r.Context()
+	logger := logging.FromContext(ctx)
 
 	repoPath := ExtractRepoPath(pathValue)
 	upstreamURL := "https://" + host + "/" + repoPath
@@ -515,6 +538,7 @@ func (s *Strategy) startClone(ctx context.Context, repo *gitclone.Repository) er
 
 			if s.config.SnapshotInterval > 0 {
 				s.scheduleSnapshotJobs(repo)
+				s.scheduleLFSSnapshotJobs(repo)
 			}
 			if s.config.RepackInterval > 0 {
 				s.scheduleRepackJobs(repo)
@@ -545,6 +569,7 @@ func (s *Strategy) startClone(ctx context.Context, repo *gitclone.Repository) er
 
 	if s.config.SnapshotInterval > 0 {
 		s.scheduleSnapshotJobs(repo)
+		s.scheduleLFSSnapshotJobs(repo)
 	}
 	if s.config.RepackInterval > 0 {
 		s.scheduleRepackJobs(repo)