GIT-BACKFILL(1)

🌟 GIT-BACKFILL(1) — Git Manual 🌟

okay bestie, welcome to the Git Manual page for git-backfill 💖 this is the one that’s giving “download the missing objects in my partial clone” energy, and we’re gonna walk through it together.

✨ NAME ✨

git-backfill — download missing objects in a partial clone. That’s the whole name, no cap.

🌸 SYNOPSIS 🌸

git backfill [--min-batch-size=<n>] [--[no-]sparse] [--[no-]include-edges] [<revision-range>]

💅 DESCRIPTION 💅

So here’s the lore: Blobless partial clones are created using git clone --filter=blob:none, and then they configure the local repository such that the Git client avoids downloading blob objects unless they are required for a local operation. Initially that means the clone and later fetches download reachable commits and trees but no blobs. Later operations that change the HEAD pointer, such as git checkout or git merge, may need to download missing blobs in order to complete their operation.

In the worst cases, commands that compute blob diffs, such as git blame, become very slow as they download the missing blobs in single-blob requests to satisfy the missing object as the Git command needs it. This leads to multiple download requests and no ability for the Git server to provide delta compression across those objects. 😭

The git backfill command provides a way for the user to request that Git downloads the missing blobs (with optional filters) such that the missing blobs representing historical versions of files can be downloaded in batches. The backfill command attempts to optimize the request by grouping blobs that appear at the same path, hopefully leading to good delta compression in the packfile sent by the server. That’s the glow-up: batch it, group by path, let the server do its delta-compression thing ✨

In this way, git backfill provides a mechanism to break a large clone into smaller chunks. Starting with a blobless partial clone with git clone --filter=blob:none and then running git backfill in the local repository provides a way to download all reachable objects in several smaller network calls than downloading the entire repository at clone time. Several smaller calls instead of one giant clone? We love to see it 🫶

By default, git backfill downloads all blobs reachable from the HEAD commit. This set can be restricted or expanded using various options below.

⚠️ THIS COMMAND IS EXPERIMENTAL. ITS BEHAVIOR MAY CHANGE IN THE FUTURE. Bestie, do not build your whole personality on the exact behavior yet 💀

🎀 OPTIONS 🎀

• --min-batch-size=<n> — specify a minimum size for a batch of missing objects to request from the server. This size may be exceeded by the last set of blobs seen at a given path. The default minimum batch size is 50,000.
• --sparse, --no-sparse — Only download objects if they appear at a path that matches the current sparse-checkout. If the sparse-checkout feature is enabled, then --sparse is assumed and can be disabled with --no-sparse.
• --include-edges, --no-include-edges — Include blobs from boundary commits in the backfill. Useful in preparation for commands like git log -p A..B or git replay --onto TARGET A..B, where A..B normally excludes A but you need the blobs from A as well. --include-edges is the default.
• <revision-range> — Backfill only blobs reachable from commits in the specified revision range. When no <revision-range> is specified, it defaults to HEAD (i.e. the whole history leading to the current commit). For a complete list of ways to spell <revision-range>, see the "Specifying Ranges" section of gitrevisions(7).

You may also use commit-limiting options understood by git-rev-list(1) such as --first-parent, --since, or pathspecs.

Most --filter=<spec> options don’t work with the purpose of git backfill, but the sparse:<oid> filter is integrated to provide a focused set of paths to download, distinct from the --sparse option.

🦋 SEE ALSO 🦋

Go read up on git-clone(1) and git-rev-list(1) — those are the besties in the SEE ALSO section 💜

👑 GIT 👑

git-backfill is part of the git(1) suite. Periodt.

---

Catch you later, bestie 🎀 — this page is from Git 2.56.0, dated 2026-09-27. Stay slay, stay patched 💅