From: Patrick Steinhardt <ps@pks.im>
Date: Tue, 16 Dec 2025 08:12:45 GMT
Subject: Re: [PATCH] docs: clarify git-rev-list(1) --filter behavior
Message-ID: <aUEUfQDJyPf6Mhtw@pks.im>
In-Reply-To: <xmqqwm2n5ivh.fsf@gitster.g>

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