What is the git clone --filter option's syntax?

Question

The Git 2.17 changelog describes this option:

• The machinery to clone & fetch, which in turn involves packing and unpacking objects, has been told how to omit certain objects using
  the filtering mechanism introduced by another topic. It now knows
  to mark the resulting pack as a promisor pack to tolerate missing
  objects, laying foundation for "narrow" clones.

Is this flag ready to be used, or is it most likely quite unstable? Does anyone know the right syntax to pass? Whatever flags I pass are rejected as being an invalid filter-spec. For example, these were my attempts to filter by directory:

git clone file://path --depth=1 --filter '--subdirectory-filter Assets' TestRepo
git clone file://path --depth=1 --filter --subdirectory-filter Assets TestRepo
git clone file://path --depth=1 --filter Assets TestRepo

Answer 1

The format for filter-spec is defined in the options section of git rev-list --help. You can also see it on github. Here's what it currently says:

--filter=<filter-spec>

Only useful with one of the --objects*; omits objects (usually blobs) from the list of printed objects. The <filter-spec> may be one of the following:

The form --filter=blob:none omits all blobs.

The form --filter=blob:limit=<n>[kmg] omits blobs larger than n bytes or units. n may be zero. The suffixes k, m, and g can be used to name units in KiB, MiB, or GiB. For example, blob:limit=1k is the same as blob:limit=1024.

The form --filter=sparse:oid=<blob-ish> uses a sparse-checkout specification contained in the blob (or blob-expression) <blob-ish> to omit blobs that would not be required for a sparse checkout on the requested refs.