patchdocs: clarify git-rev-list(1) --filter behavior

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

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

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

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

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