Measure What Git Sparse Checkout Actually Saves

Git sparse checkout and partial clone reduce different things. Sparse checkout limits which tracked paths appear in the working tree. Partial clone limits which reachable Git objects arrive initially. Use both when you want a small working directory and deferred blob transfer; use sparse checkout alone when the full object database must remain available offline.

Our reproduced comparison used one two-commit origin and the same selected service-a directory. A full clone and a sparse-only clone each stored 8,393,490 bytes under .git/objects. The blobless sparse clone stored 3,436 bytes and reported three missing objects. Its worktree looked just as small as the sparse-only worktree, so a short file listing could not reveal the transfer difference.

This practical guide is for developers and build engineers who can use Git and a shell. It ran with Git 2.47.3 on Debian 13, needs Python 3 only to generate deterministic incompressible fixture blobs, uses no account or external repository, and removes one marker-owned path. The local bare origin explicitly enables upload-pack filtering; a real Git host must also support the requested partial-clone filter.

Choose the Storage Boundary Before the Flag

A Git working tree contains the files you edit. The object database under .git/objects stores commits, trees, blobs and tags. A blob is normally file content. Hiding a path from the worktree does not imply that its blob is absent from the object database.

Git’s current sparse-checkout documentation defines the feature around working-tree population. Cone mode, now the default for directory inputs, lets Git represent common directory-shaped selections efficiently. A sparse index can reduce index work further, but neither setting is a network object filter.

Git’s clone reference gives --sparse and --filter separate jobs. --sparse begins with a limited worktree. --filter=blob:none requests a partial clone that leaves blobs out until Git needs their contents. Git records the remote as a promisor: the local repository is allowed to reference objects that the remote has promised to supply later.

History depth is another axis. A shallow clone such as --depth=1 truncates reachable commit history; blob:none preserves commit and tree history while deferring file-content blobs. Do not substitute one merely because both can make an initial clone smaller.

Start with a private, fixed lab path and record the tested client. Every later block rechecks the ownership marker before it changes state.

set -euo pipefail
LAB=/tmp/voxfor-git-sparse-160
MARKER="$LAB/.voxfor-git-sparse-lab"
[[ ! -e "$LAB" ]] || { printf 'Refusing existing path: %s\n' "$LAB" >&2; exit 9; }
install -d -m 0700 "$LAB"
printf '%s\n' voxfor-git-sparse-lab-v1 > "$MARKER"
printf 'git_version=%s\n' "$(git --version | awk '{print $3}')"
printf 'lab_root=%s scope=marker-owned\n' "$LAB"

Build One Origin With Measurable Hidden Blobs

To expose object-store differences without wasting space, the fixture uses two incompressible 4 MiB files outside service-a; a second commit changes only the selected service. Python derives every 32-byte block from a fixed label and counter, so repeated runs produce the same content.

set -euo pipefail
LAB=/tmp/voxfor-git-sparse-160
grep -qx 'voxfor-git-sparse-lab-v1' "$LAB/.voxfor-git-sparse-lab"
git init -q "$LAB/source"
git -C "$LAB/source" config user.name 'Voxfor Lab'
git -C "$LAB/source" config user.email 'voxfor-lab.invalid'
install -d "$LAB/source/service-a" "$LAB/source/service-b" "$LAB/source/media"
printf 'service=a\nrevision=1\n' > "$LAB/source/service-a/app.conf"
python3 - "$LAB/source/service-b/payload.bin" "$LAB/source/media/archive.bin" <<'PY'
import hashlib
import pathlib
import sys

for target, label in zip(sys.argv[1:], (b'service-b', b'media-archive')):
    path = pathlib.Path(target)
    with path.open('wb') as stream:
        for counter in range(131072):
            stream.write(hashlib.sha256(label + counter.to_bytes(8, 'big')).digest())
PY
git -C "$LAB/source" add service-a service-b media
git -C "$LAB/source" commit -qm 'Create deterministic monorepo fixture'
printf 'revision=2\n' >> "$LAB/source/service-a/app.conf"
git -C "$LAB/source" commit -qam 'Update selected service'
git clone -q --bare "$LAB/source" "$LAB/origin.git"
git -C "$LAB/origin.git" config uploadpack.allowFilter true
git -C "$LAB/origin.git" config uploadpack.allowAnySHA1InWant true
printf 'origin_commits=%s large_blob_bytes=%s\n' \
  "$(git -C "$LAB/origin.git" rev-list --count --all)" \
  "$(git -C "$LAB/source" cat-file -s HEAD:service-b/payload.bin)"

Those server settings are lab-specific proof that filtering is available. On a hosted origin, inspect clone warnings and the resulting promisor configuration instead of assuming the server honored blob:none. Git can fall back to a fuller transfer when a server does not recognize filtering, and that changes the expected storage result.

Make Full, Sparse-Only, and Blobless Sparse Clones

All three clones use the Git-aware file:// transport rather than local hard-link optimization. That keeps the object-byte comparison meaningful on one host. The two sparse clones then select the same service-a cone.

set -euo pipefail
LAB=/tmp/voxfor-git-sparse-160
grep -qx 'voxfor-git-sparse-lab-v1' "$LAB/.voxfor-git-sparse-lab"
ORIGIN_URL="file://$LAB/origin.git"
git clone -q "$ORIGIN_URL" "$LAB/full"
git clone -q --sparse "$ORIGIN_URL" "$LAB/sparse-only"
git -C "$LAB/sparse-only" sparse-checkout set service-a
git clone -q --filter=blob:none --sparse "$ORIGIN_URL" "$LAB/blobless-sparse"
git -C "$LAB/blobless-sparse" sparse-checkout set service-a

GitHub’s contributor article Bring your monorepo down to size with sparse-checkout is the strongest practical competitor for this query. It shows fewer received objects when partial clone and sparse checkout work together. This lab adds byte counts, missing-object counts and an unavailable-origin test on the same fixture.

Now enumerate only worktree files, measure .git/objects, and ask rev-list --missing=print to report referenced objects that are not present. The command does not treat a promised missing object as corruption; it prints that intentional boundary with a leading question mark.

set -euo pipefail
LAB=/tmp/voxfor-git-sparse-160
grep -qx 'voxfor-git-sparse-lab-v1' "$LAB/.voxfor-git-sparse-lab"
for name in full sparse-only blobless-sparse; do
  files=$(find "$LAB/$name" -path "$LAB/$name/.git" -prune -o -type f -printf '%P\n' \
    | sort | paste -sd, -)
  object_bytes=$(du -sb "$LAB/$name/.git/objects" | awk '{print $1}')
  missing=$(git -C "$LAB/$name" rev-list --objects --all --missing=print \
    | awk '/^\?/{count++} END{print count+0}')
  printf '%s worktree_files=%s object_bytes=%s missing_objects=%s\n' \
    "$name" "$files" "$object_bytes" "$missing"
done

Two rows have worktree_files=service-a/app.conf, yet only the blobless clone omits objects. Worktree equality is not object-store equality. In this fixture, sparse checkout alone saved the two visible 4 MiB files from worktree materialization, while the ordinary clone transport still delivered their blobs to the local object database.

Read the Promisor Contract, Then Trigger Hydration

Confirm the difference without relying only on byte totals. The sparse-only clone has no promisor flag and can read the hidden media blob locally. The blobless sparse clone records both remote.origin.promisor=true and remote.origin.partialclonefilter=blob:none.

set -euo pipefail
LAB=/tmp/voxfor-git-sparse-160
grep -qx 'voxfor-git-sparse-lab-v1' "$LAB/.voxfor-git-sparse-lab"
[[ -f "$LAB/sparse-only/service-a/app.conf" && ! -e "$LAB/sparse-only/service-b" ]]
[[ -f "$LAB/blobless-sparse/service-a/app.conf" && ! -e "$LAB/blobless-sparse/service-b" ]]
[[ "$(git -C "$LAB/sparse-only" config --get remote.origin.promisor || true)" != true ]]
[[ "$(git -C "$LAB/blobless-sparse" config --get remote.origin.promisor)" == true ]]
[[ "$(git -C "$LAB/blobless-sparse" config --get remote.origin.partialclonefilter)" == blob:none ]]
printf 'sparse_only_hidden_blob_local_bytes=%s\n' \
  "$(git -C "$LAB/sparse-only" cat-file -s HEAD:media/archive.bin)"
printf 'blobless_promisor=%s filter=%s\n' \
  "$(git -C "$LAB/blobless-sparse" config --get remote.origin.promisor)" \
  "$(git -C "$LAB/blobless-sparse" config --get remote.origin.partialclonefilter)"

Hydration means fetching an object when an operation first needs it. Expanding the cone to service-b requires its 4 MiB blob, so object bytes should grow and the checked-out file must match the source SHA-256.

set -euo pipefail
LAB=/tmp/voxfor-git-sparse-160
grep -qx 'voxfor-git-sparse-lab-v1' "$LAB/.voxfor-git-sparse-lab"
before_bytes=$(du -sb "$LAB/blobless-sparse/.git/objects" | awk '{print $1}')
git -C "$LAB/blobless-sparse" sparse-checkout add service-b
after_service_bytes=$(du -sb "$LAB/blobless-sparse/.git/objects" | awk '{print $1}')
source_hash=$(sha256sum "$LAB/source/service-b/payload.bin" | awk '{print $1}')
clone_hash=$(sha256sum "$LAB/blobless-sparse/service-b/payload.bin" | awk '{print $1}')
[[ "$source_hash" == "$clone_hash" && "$after_service_bytes" -gt "$before_bytes" ]]
printf 'lazy_fetch=service-b before_object_bytes=%s after_object_bytes=%s sha256_match=yes\n' \
  "$before_bytes" "$after_service_bytes"

Lazy transfer is useful, but it creates an availability condition. The next negative control identifies the still-missing media blob, moves only the marker-owned bare origin aside, captures the failed fetch, restores the origin, and verifies the recovered content. Restoration happens before any assertion on the expected error text.

set -euo pipefail
LAB=/tmp/voxfor-git-sparse-160
grep -qx 'voxfor-git-sparse-lab-v1' "$LAB/.voxfor-git-sparse-lab"
media_oid=$(git -C "$LAB/source" rev-parse HEAD:media/archive.bin)
git -C "$LAB/blobless-sparse" rev-list --objects --all --missing=print | grep -q "^?$media_oid"
mv "$LAB/origin.git" "$LAB/origin.offline"
set +e
git -C "$LAB/blobless-sparse" show HEAD:media/archive.bin >/dev/null 2>"$LAB/offline.err"
offline_rc=$?
set -e
mv "$LAB/origin.offline" "$LAB/origin.git"
[[ "$offline_rc" -ne 0 ]]
grep -Eq 'does not appear to be a git repository|Could not read from remote repository|unable to access|not found' "$LAB/offline.err"
printf 'origin_offline_missing_blob_rc=%s lazy_fetch_required=yes\n' "$offline_rc"
git -C "$LAB/blobless-sparse" show HEAD:media/archive.bin > "$LAB/media.restored.bin"
[[ "$(sha256sum "$LAB/media.restored.bin" | awk '{print $1}')" == \
   "$(sha256sum "$LAB/source/media/archive.bin" | awk '{print $1}')" ]]
printf 'origin_restored media_sha256_match=yes final_object_bytes=%s\n' \
  "$(du -sb "$LAB/blobless-sparse/.git/objects" | awk '{print $1}')"

Exit 128 is not evidence that the repository is corrupt. It proves this local clone still depended on its promisor for that blob. A laptop that must build on an airplane, an incident workstation isolated from the network, or an archival job should hydrate and verify the required object set before disconnection—or use a complete clone, mirror or bundle designed for that recovery task.

Convert the Receipt Into a Workstation or CI Decision

Environment changes the correct choice:

• Large online monorepo: combine blob:none with cone-mode sparse checkout when teams own directory-shaped components and the origin is reliably reachable. Measure the actual cone and subsequent hydration, not only initial clone time.
• Offline or air-gapped work: sparse checkout alone can keep the worktree focused while retaining all reachable objects. Confirm that submodules and Git LFS objects have their own complete offline contract; parent-repository sparsity does not silently fetch them.
• Ephemeral CI: a blobless sparse clone can avoid downloading unrelated content, but cold jobs may pay repeated hydration costs. A persistent runner, cache or prebuilt source bundle changes the calculation. Voxfor’s self-hosted GitHub Actions runner guide covers runner identity, isolation, secrets and lifecycle; clone flags do not replace those controls.
• Release deployment: a minimal checkout can stage source efficiently, but it is not an atomic release artifact or rollback plan. Keep the repository optimization separate from the GitHub deployment and rollback workflow.
• Regression search: partial clones can fetch blobs while a predicate moves across history. If network variability would make results ambiguous, hydrate the test range first and use a deterministic git bisect run boundary.
• Forge recovery: a developer clone does not contain issues, users, permissions, configuration, attachments or every external object store. A self-hosted origin needs a separate Forgejo restore rehearsal.

Run the final assertions while the origin is available, then remove only the marked lab.

set -euo pipefail
LAB=/tmp/voxfor-git-sparse-160
MARKER="$LAB/.voxfor-git-sparse-lab"
grep -qx 'voxfor-git-sparse-lab-v1' "$MARKER"
full_missing=$(git -C "$LAB/full" rev-list --objects --all --missing=print \
  | awk '/^\?/{count++} END{print count+0}')
sparse_missing=$(git -C "$LAB/sparse-only" rev-list --objects --all --missing=print \
  | awk '/^\?/{count++} END{print count+0}')
partial_missing=$(git -C "$LAB/blobless-sparse" rev-list --objects --all --missing=print \
  | awk '/^\?/{count++} END{print count+0}')
[[ "$full_missing" -eq 0 && "$sparse_missing" -eq 0 ]]
printf 'verification=pass full_missing=%s sparse_only_missing=%s blobless_missing_after_two_fetches=%s\n' \
  "$full_missing" "$sparse_missing" "$partial_missing"
rm -rf --one-file-system "$LAB"
[[ ! -e "$LAB" ]]
printf 'cleanup=complete\n'

One complete Debian 13 run produced this representative receipt:

git_version=2.47.3
lab_root=/tmp/voxfor-git-sparse-160 scope=marker-owned
origin_commits=2 large_blob_bytes=4194304
full worktree_files=media/archive.bin,service-a/app.conf,service-b/payload.bin object_bytes=8393490 missing_objects=0
sparse-only worktree_files=service-a/app.conf object_bytes=8393490 missing_objects=0
blobless-sparse worktree_files=service-a/app.conf object_bytes=3436 missing_objects=3
sparse_only_hidden_blob_local_bytes=4194304
blobless_promisor=true filter=blob:none
lazy_fetch=service-b before_object_bytes=3436 after_object_bytes=4200218 sha256_match=yes
origin_offline_missing_blob_rc=128 lazy_fetch_required=yes
origin_restored media_sha256_match=yes final_object_bytes=8397000
verification=pass full_missing=0 sparse_only_missing=0 blobless_missing_after_two_fetches=1
cleanup=complete

The comparison is accepted when full and sparse-only clones report zero missing reachable objects, both sparse worktrees contain service-a/app.conf but not service-b initially, only the blobless clone records the promisor and blob:none filter, its object bytes grow after adding service-b, both hydrated blobs match the source SHA-256, the unavailable-origin control fails before restoration, and the marker-owned path is absent after cleanup. The reproduced run met every condition.

Lab rollback first restores origin.offline to origin.git if the negative-control interval was interrupted, then deletes only /tmp/voxfor-git-sparse-160 after the marker equals voxfor-git-sparse-lab-v1. For a real repository, disabling sparse checkout repopulates the worktree but does not turn a partial clone into a guaranteed complete archive. Keep the original remote URL, preserve uncommitted work, hydrate and verify required objects, or replace the disposable clone from the authoritative origin rather than deleting uncertain repository state.

For more Git, CI and infrastructure procedures, browse Voxfor’s DevOps operations library.