Sparse checkout vs partial clone: use both deliberately

Sparse checkout controls which tracked paths appear in the working tree. Partial clone controls which Git objects are downloaded in advance. They can be combined, but enabling one does not establish that the other is active. Sparse-checkout manual, partial-clone design

This distinction matters when a job needs a small directory inside a large repository. A small working tree alone does not tell you how many objects traveled over the network. A filtered object download alone does not guarantee that checkout will avoid fetching the files needed for a full working tree.

Three independent dimensions

Mechanism	Primary question	What it does not establish
Sparse checkout	Which paths should be materialized?	That all other blobs were excluded from download
Partial clone	Which objects can be fetched later?	That a full working-tree checkout is inexpensive
Shallow clone	How much commit history is initially included?	That current file contents are small

Git documents shallow history and partial object filtering as independent mechanisms. A promisor remote supplies omitted objects when they are needed, which introduces a dependency on network and remote availability for those reads. Partial-clone design

A practical starting configuration

Replace the URL and paths with a repository you are permitted to access. This example starts from the remote’s default branch; it is a setup template, not a benchmark result.

git clone --filter=blob:none --sparse REPOSITORY_URL agent-work
cd agent-work
git sparse-checkout set --cone services/api packages/shared
git rev-parse HEAD
git sparse-checkout list
git config --get remote.origin.promisor
git config --get remote.origin.partialclonefilter

--filter=blob:none requests deferred blob downloads. --sparse initially limits the checkout, and the next command selects directories. Cone mode also includes files alongside selected directories’ ancestors, including root-level files; it is not a guarantee that precisely two directories and nothing else will exist. Server support and the actual command output must be checked. Git clone options, cone-pattern rules

Prove the smaller input is sufficient

Run the real task from the resulting working tree. A package may need root configuration, a shared library, a code generator, or files located by walking the repository. Expand the selection from observed dependencies. Preserve the tested path list alongside the job definition so later changes are reviewable.

For a comparison, resolve one immutable commit and use it in every variant. Record network bytes across the whole task, because a later diff or history command can demand-fetch omitted objects. Check the warning output as well as configuration: a requested filter is not evidence of an effective filter.

Keep clone tuning separate from access control. Omitting a path from checkout does not grant or revoke permission to retrieve it. If a service needs directory-level authorization, evaluate that explicitly.

Before considering another source control system, use this configuration as one candidate baseline in the agent checkout evaluation plan.

Sources

• Git sparse-checkout
• Git partial-clone design
• Git clone