[PATCH] docs: clarify git-rev-list(1) --filter behavior

[PATCH] docs: clarify git-rev-list(1) --filter behavior

[Justin Tobler]

When using the --filter option for git-rev-list(1), objects that are
explicitly provided ignore filters and are always printed unless the
--filter-provided-objects option is also specified. Clarify this
behavior in the documentation.

Signed-off-by: Justin Tobler <jltobler@gmail.com>
---

Greetings,

This small documentation update is in response to discussion from [1].

Thanks,
-Justin

[1]: <aT-djS-TrQJxxV8i@pks.im>

---
 Documentation/rev-list-options.adoc | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/Documentation/rev-list-options.adoc b/Documentation/rev-list-options.adoc
index d9665d82c8..453ec59057 100644
--- a/Documentation/rev-list-options.adoc
+++ b/Documentation/rev-list-options.adoc
@@ -983,7 +983,9 @@ to name units in KiB, MiB, or GiB.  For example, `blob:limit=1k`
 is the same as 'blob:limit=1024'.
 +
 The form `--filter=object:type=(tag|commit|tree|blob)` omits all objects
-which are not of the requested type.
+which are not of the requested type. Note that explicitly provided objects
+ignore filters and are always printed unless `--filter-provided-objects` is
+also specified.
 +
 The form `--filter=sparse:oid=<blob-ish>` uses a sparse-checkout
 specification contained in the blob (or blob-expression) _<blob-ish>_

base-commit: d8af7cadaa79d5837d73ec949e10b57dedb43e9b
-- 
2.52.0.209.ge85ae279b0

Re: [PATCH] docs: clarify git-rev-list(1) --filter behavior

[Junio C Hamano]

Justin Tobler <jltobler@gmail.com> writes:

> When using the --filter option for git-rev-list(1), objects that are
> explicitly provided ignore filters and are always printed unless the
> --filter-provided-objects option is also specified. Clarify this
> behavior in the documentation.
>
> Signed-off-by: Justin Tobler <jltobler@gmail.com>
> ---
>
> Greetings,
>
> This small documentation update is in response to discussion from [1].
>
> Thanks,
> -Justin
>
> [1]: <aT-djS-TrQJxxV8i@pks.im>
>
> ---
>  Documentation/rev-list-options.adoc | 4 +++-
>  1 file changed, 3 insertions(+), 1 deletion(-)
>
> diff --git a/Documentation/rev-list-options.adoc b/Documentation/rev-list-options.adoc
> index d9665d82c8..453ec59057 100644
> --- a/Documentation/rev-list-options.adoc
> +++ b/Documentation/rev-list-options.adoc
> @@ -983,7 +983,9 @@ to name units in KiB, MiB, or GiB.  For example, `blob:limit=1k`
>  is the same as 'blob:limit=1024'.
>  +
>  The form `--filter=object:type=(tag|commit|tree|blob)` omits all objects
> -which are not of the requested type.
> +which are not of the requested type. Note that explicitly provided objects
> +ignore filters and are always printed unless `--filter-provided-objects` is
> +also specified.

The above documents the status quo correctly, so let's queue, but it
is unfortunate that we need an extra option to do this.

Re: [PATCH] docs: clarify git-rev-list(1) --filter behavior

[Patrick Steinhardt]

On Tue, Dec 16, 2025 at 10:13:22AM +0900, Junio C Hamano wrote:
> > diff --git a/Documentation/rev-list-options.adoc b/Documentation/rev-list-options.adoc
> > index d9665d82c8..453ec59057 100644
> > --- a/Documentation/rev-list-options.adoc
> > +++ b/Documentation/rev-list-options.adoc
> > @@ -983,7 +983,9 @@ to name units in KiB, MiB, or GiB.  For example, `blob:limit=1k`
> >  is the same as 'blob:limit=1024'.
> >  +
> >  The form `--filter=object:type=(tag|commit|tree|blob)` omits all objects
> > -which are not of the requested type.
> > +which are not of the requested type. Note that explicitly provided objects
> > +ignore filters and are always printed unless `--filter-provided-objects` is
> > +also specified.
> 
> The above documents the status quo correctly, so let's queue, but it
> is unfortunate that we need an extra option to do this.

True. I didn't feel comfortable to change the default to also filter
provided objects when I discovered that we don't, hence the new option.
It's not great though as it certainly is surprising behaviour, but I'm
not sure whether we can really change it without breaking existing
users. Oh, well...

In any case, the documentation addition is very welcome, thanks!

Patrick

Re: [PATCH] docs: clarify git-rev-list(1) --filter behavior

[Justin Tobler]

On 25/12/16 09:12AM, Patrick Steinhardt wrote:
> On Tue, Dec 16, 2025 at 10:13:22AM +0900, Junio C Hamano wrote:
> > > diff --git a/Documentation/rev-list-options.adoc b/Documentation/rev-list-options.adoc
> > > index d9665d82c8..453ec59057 100644
> > > --- a/Documentation/rev-list-options.adoc
> > > +++ b/Documentation/rev-list-options.adoc
> > > @@ -983,7 +983,9 @@ to name units in KiB, MiB, or GiB.  For example, `blob:limit=1k`
> > >  is the same as 'blob:limit=1024'.
> > >  +
> > >  The form `--filter=object:type=(tag|commit|tree|blob)` omits all objects
> > > -which are not of the requested type.
> > > +which are not of the requested type. Note that explicitly provided objects
> > > +ignore filters and are always printed unless `--filter-provided-objects` is
> > > +also specified.
> > 
> > The above documents the status quo correctly, so let's queue, but it
> > is unfortunate that we need an extra option to do this.
> 
> True. I didn't feel comfortable to change the default to also filter
> provided objects when I discovered that we don't, hence the new option.
> It's not great though as it certainly is surprising behaviour, but I'm
> not sure whether we can really change it without breaking existing
> users. Oh, well...

Out of curiousity, are there any known use-cases where a user _would_
want the provided objects printed along with the filtered ones? From my
naive perspective it almost doesn't even sound useful and appears to
just be a sharp edge. This maybe not worthing worrying too much about
though.

-Justin

Re: [PATCH] docs: clarify git-rev-list(1) --filter behavior

[Patrick Steinhardt]

On Tue, Dec 16, 2025 at 08:36:56AM -0600, Justin Tobler wrote:
> On 25/12/16 09:12AM, Patrick Steinhardt wrote:
> > On Tue, Dec 16, 2025 at 10:13:22AM +0900, Junio C Hamano wrote:
> > > > diff --git a/Documentation/rev-list-options.adoc b/Documentation/rev-list-options.adoc
> > > > index d9665d82c8..453ec59057 100644
> > > > --- a/Documentation/rev-list-options.adoc
> > > > +++ b/Documentation/rev-list-options.adoc
> > > > @@ -983,7 +983,9 @@ to name units in KiB, MiB, or GiB.  For example, `blob:limit=1k`
> > > >  is the same as 'blob:limit=1024'.
> > > >  +
> > > >  The form `--filter=object:type=(tag|commit|tree|blob)` omits all objects
> > > > -which are not of the requested type.
> > > > +which are not of the requested type. Note that explicitly provided objects
> > > > +ignore filters and are always printed unless `--filter-provided-objects` is
> > > > +also specified.
> > > 
> > > The above documents the status quo correctly, so let's queue, but it
> > > is unfortunate that we need an extra option to do this.
> > 
> > True. I didn't feel comfortable to change the default to also filter
> > provided objects when I discovered that we don't, hence the new option.
> > It's not great though as it certainly is surprising behaviour, but I'm
> > not sure whether we can really change it without breaking existing
> > users. Oh, well...
> 
> Out of curiousity, are there any known use-cases where a user _would_
> want the provided objects printed along with the filtered ones? From my
> naive perspective it almost doesn't even sound useful and appears to
> just be a sharp edge. This maybe not worthing worrying too much about
> though.

I don't really have an idea, but that's exactly the problem here.
Filters are for example used by partial clones, and I don't want to
break those because I'm not aware of some of the intricacies. Which
doesn't mean that there _are_ use cases where this is actually the
desired behaviour, but rather that there needs to be some research to
come to a conclusion here.

Patrick

Re: [PATCH] docs: clarify git-rev-list(1) --filter behavior

[Junio C Hamano]

Justin Tobler <jltobler@gmail.com> writes:

>> True. I didn't feel comfortable to change the default to also filter
>> provided objects when I discovered that we don't, hence the new option.
>> It's not great though as it certainly is surprising behaviour, but I'm
>> not sure whether we can really change it without breaking existing
>> users. Oh, well...
>
> Out of curiousity, are there any known use-cases where a user _would_
> want the provided objects printed along with the filtered ones? From my
> naive perspective it almost doesn't even sound useful and appears to
> just be a sharp edge. This maybe not worthing worrying too much about
> though.

Perhaps there is no good use case (and that is why I hinted that we
may want to "fix" it someday).

It however is understandable that nobody noticed it because for the
primarily intended use case of "filter", i.e., object transfer into
lazy clone, you use commit-ishes to describe a range to be
listed/transferred, and you never filter out the commmit objects,
perhaps?