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

From: Patrick Steinhardt <ps@pks.im>
Date: Dec 16, 2025, 08:12 UTC
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:

Show 15 quoted lines

> > 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