# [PATCH] docs: clarify git-rev-list(1) --filter behavior 6 messages from 2025-12-15 to 2025-12-16. Participants: Justin Tobler, Junio C Hamano, Patrick Steinhardt. Thread: https://gitlist.dev/t/64629 ## Justin Tobler, 2025-12-15 20:05 Subject: [PATCH] docs: clarify git-rev-list(1) --filter behavior Message-ID: <20251215200512.2694155-1-jltobler@gmail.com> URL: https://gitlist.dev/e/20251215200512.2694155-1-jltobler%40gmail.com ``` 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 --- Greetings, This small documentation update is in response to discussion from [1]. Thanks, -Justin [1]: --- 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. + The form `--filter=sparse:oid=` uses a sparse-checkout specification contained in the blob (or blob-expression) __ base-commit: d8af7cadaa79d5837d73ec949e10b57dedb43e9b -- 2.52.0.209.ge85ae279b0 ``` ## Junio C Hamano, 2025-12-16 01:13 Subject: Re: [PATCH] docs: clarify git-rev-list(1) --filter behavior Message-ID: URL: https://gitlist.dev/e/xmqqwm2n5ivh.fsf%40gitster.g In-Reply-To: <20251215200512.2694155-1-jltobler@gmail.com> ``` Justin Tobler writes: > 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 > --- > > Greetings, > > This small documentation update is in response to discussion from [1]. > > Thanks, > -Justin > > [1]: > > --- > 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. The above documents the status quo correctly, so let's queue, but it is unfortunate that we need an extra option to do this. ``` ## Patrick Steinhardt, 2025-12-16 08:12 Subject: Re: [PATCH] docs: clarify git-rev-list(1) --filter behavior Message-ID: URL: https://gitlist.dev/e/aUEUfQDJyPf6Mhtw%40pks.im In-Reply-To: ``` 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 ``` ## Justin Tobler, 2025-12-16 14:36 Subject: Re: [PATCH] docs: clarify git-rev-list(1) --filter behavior Message-ID: URL: https://gitlist.dev/e/xnstt6myzzfyq65w73xuqg7cfso3bdw6tw33shrery4e4gi2zy%40pfxq2pjmb2hm In-Reply-To: ``` 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. -Justin ``` ## Patrick Steinhardt, 2025-12-16 14:49 Subject: Re: [PATCH] docs: clarify git-rev-list(1) --filter behavior Message-ID: URL: https://gitlist.dev/e/aUFxbDPucKr42fIJ%40pks.im In-Reply-To: ``` 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 ``` ## Junio C Hamano, 2025-12-16 18:07 Subject: Re: [PATCH] docs: clarify git-rev-list(1) --filter behavior Message-ID: URL: https://gitlist.dev/e/xmqqbjjy47xn.fsf%40gitster.g In-Reply-To: ``` Justin Tobler writes: >> 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. Perhaps there is no good use case (and that is why I hinted that we may want to "fix" it someday). It however is understandable that nobody noticed it because for the primarily intended use case of "filter", i.e., object transfer into lazy clone, you use commit-ishes to describe a range to be listed/transferred, and you never filter out the commmit objects, perhaps? ```