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

From: Patrick Steinhardt <[email-masked]>
Date: Tue, 16 Dec 2025 09:12:45 +0100

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