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

[Patrick Steinhardt <ps@pks.im>]

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