Introduction

git clone --filter=... is part of Git's partial clone support. It lets you reduce the amount of object data downloaded during clone, which is especially useful for large repositories where you do not need every blob immediately.

Basic Syntax

The command shape is:

git clone --filter=<filter-spec> <repository> [directory]

The key piece is <filter-spec>, which describes what objects should be omitted or limited during the initial clone.

Common Filter Specs

The most common values are:

• 'blob:none'
• 'blob:limit=<size>'
• 'tree:<depth>'

Examples:

git clone --filter=blob:none https://example.com/repo.git

This downloads commits and trees but omits file contents until they are needed.

git clone --filter=blob:limit=1m https://example.com/repo.git

This allows smaller blobs but avoids large ones during the initial transfer.

git clone --filter=tree:0 https://example.com/repo.git

This is a more aggressive form that minimizes tree objects as well.

What blob:none Usually Means in Practice

blob:none is the most common partial clone option because it preserves history structure while postponing file-content downloads.

That is a good fit for:

• large monorepos
• code search tasks
• metadata inspection
• tooling that does not need the full working tree immediately

As soon as Git needs a missing blob, it can fetch it lazily from the remote, assuming the server supports the protocol.

Partial Clone Is Different from Shallow Clone

People often confuse --filter with --depth.

• '--depth reduces history length'
• '--filter reduces object transfer'

You can combine them:

git clone --depth=1 --filter=blob:none https://example.com/repo.git

That gives you both a shallow history and reduced object payload.

Server Support Matters

--filter only works properly when the remote server supports partial clone and object filtering. If the server does not support it, the clone may fail or silently behave more like a full clone depending on the environment and Git version.

That means the syntax alone is not enough. The remote and client must both support the feature path you are trying to use.

Useful Companion Options

Partial clone is often combined with sparse checkout in very large repositories.

git clone --filter=blob:none --sparse https://example.com/repo.git
cd repo
git sparse-checkout set src docs

This is a powerful combination when you want only part of the tree plus delayed blob fetching. It reduces both initial transfer time and local checkout noise for monorepos where you only need a few subdirectories.

Check the Promisor Remote Setup

After a partial clone, Git tracks the remote as a promisor source for missing objects. You can inspect relevant config values if you are debugging behavior:

git config --get remote.origin.promisor
git config --get remote.origin.partialclonefilter

This helps confirm whether the repository was actually cloned with a filter or whether something fell back to a fuller object set.

Common Pitfalls

The biggest mistake is treating --filter as a synonym for shallow clone. It is about object filtering, not about truncating commit history.

Another issue is using --filter against a server that does not support partial clone properly and then assuming the syntax itself is wrong.

A third problem is expecting filtered clones to avoid all later network access. With options such as blob:none, missing objects may still be fetched on demand later.

Summary

• The syntax is git clone --filter=<filter-spec> <repository> [directory].
• Common filter specs include blob:none, blob:limit=<size>, and tree:<depth>.
• '--filter controls transferred object data, not history depth.'
• You can combine it with options such as --depth and --sparse.
• Partial clone depends on server support as well as client support.