{"thread":{"id":"64629","subject":"[PATCH] docs: clarify git-rev-list(1) --filter behavior","startedAt":"2025-12-15T20:05:28Z","lastAt":"2025-12-16T18:07:19Z","messageCount":6,"participants":["Justin Tobler","Junio C Hamano","Patrick Steinhardt"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"532199","messageId":"20251215200512.2694155-1-jltobler@gmail.com","threadId":"64629","inReplyTo":null,"subject":"[PATCH] docs: clarify git-rev-list(1) --filter behavior","fromName":"Justin Tobler","fromEmail":"jltobler@gmail.com","sentAt":"2025-12-15T20:05:12Z","receivedAt":"2025-12-15T20:05:28Z","isPatch":true,"sender":{"key":"jltobler@gmail.com","avatar":"https://avatars.githubusercontent.com/u/53454972?v=4"},"body":"When using the --filter option for git-rev-list(1), objects that are\nexplicitly provided ignore filters and are always printed unless the\n--filter-provided-objects option is also specified. Clarify this\nbehavior in the documentation.\n\nSigned-off-by: Justin Tobler \n---\n\nGreetings,\n\nThis small documentation update is in response to discussion from [1].\n\nThanks,\n-Justin\n\n[1]: \n\n---\n Documentation/rev-list-options.adoc | 4 +++-\n 1 file changed, 3 insertions(+), 1 deletion(-)\n\ndiff --git a/Documentation/rev-list-options.adoc b/Documentation/rev-list-options.adoc\nindex d9665d82c8..453ec59057 100644\n--- a/Documentation/rev-list-options.adoc\n+++ b/Documentation/rev-list-options.adoc\n@@ -983,7 +983,9 @@ to name units in KiB, MiB, or GiB. For example, `blob:limit=1k`\n is the same as 'blob:limit=1024'.\n +\n The form `--filter=object:type=(tag|commit|tree|blob)` omits all objects\n-which are not of the requested type.\n+which are not of the requested type. Note that explicitly provided objects\n+ignore filters and are always printed unless `--filter-provided-objects` is\n+also specified.\n +\n The form `--filter=sparse:oid=` uses a sparse-checkout\n specification contained in the blob (or blob-expression) __\n\nbase-commit: d8af7cadaa79d5837d73ec949e10b57dedb43e9b\n-- \n2.52.0.209.ge85ae279b0\n\n"},{"id":"532227","messageId":"xmqqwm2n5ivh.fsf@gitster.g","threadId":"64629","inReplyTo":"20251215200512.2694155-1-jltobler@gmail.com","subject":"Re: [PATCH] docs: clarify git-rev-list(1) --filter behavior","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2025-12-16T01:13:22Z","receivedAt":"2025-12-16T01:13:25Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Justin Tobler writes:\n\n> When using the --filter option for git-rev-list(1), objects that are\n> explicitly provided ignore filters and are always printed unless the\n> --filter-provided-objects option is also specified. Clarify this\n> behavior in the documentation.\n>\n> Signed-off-by: Justin Tobler \n> ---\n>\n> Greetings,\n>\n> This small documentation update is in response to discussion from [1].\n>\n> Thanks,\n> -Justin\n>\n> [1]: \n>\n> ---\n> Documentation/rev-list-options.adoc | 4 +++-\n> 1 file changed, 3 insertions(+), 1 deletion(-)\n>\n> diff --git a/Documentation/rev-list-options.adoc b/Documentation/rev-list-options.adoc\n> index d9665d82c8..453ec59057 100644\n> --- a/Documentation/rev-list-options.adoc\n> +++ b/Documentation/rev-list-options.adoc\n> @@ -983,7 +983,9 @@ to name units in KiB, MiB, or GiB. For example, `blob:limit=1k`\n> is the same as 'blob:limit=1024'.\n> +\n> The form `--filter=object:type=(tag|commit|tree|blob)` omits all objects\n> -which are not of the requested type.\n> +which are not of the requested type. Note that explicitly provided objects\n> +ignore filters and are always printed unless `--filter-provided-objects` is\n> +also specified.\n\nThe above documents the status quo correctly, so let's queue, but it\nis unfortunate that we need an extra option to do this.\n\n"},{"id":"532243","messageId":"aUEUfQDJyPf6Mhtw@pks.im","threadId":"64629","inReplyTo":"xmqqwm2n5ivh.fsf@gitster.g","subject":"Re: [PATCH] docs: clarify git-rev-list(1) --filter behavior","fromName":"Patrick Steinhardt","fromEmail":"ps@pks.im","sentAt":"2025-12-16T08:12:45Z","receivedAt":"2025-12-16T08:12:51Z","isPatch":true,"sender":{"key":"ps@pks.im","avatar":"https://avatars.githubusercontent.com/u/4056630?v=4"},"body":"On Tue, Dec 16, 2025 at 10:13:22AM +0900, Junio C Hamano wrote:\n> > diff --git a/Documentation/rev-list-options.adoc b/Documentation/rev-list-options.adoc\n> > index d9665d82c8..453ec59057 100644\n> > --- a/Documentation/rev-list-options.adoc\n> > +++ b/Documentation/rev-list-options.adoc\n> > @@ -983,7 +983,9 @@ to name units in KiB, MiB, or GiB. For example, `blob:limit=1k`\n> > is the same as 'blob:limit=1024'.\n> > +\n> > The form `--filter=object:type=(tag|commit|tree|blob)` omits all objects\n> > -which are not of the requested type.\n> > +which are not of the requested type. Note that explicitly provided objects\n> > +ignore filters and are always printed unless `--filter-provided-objects` is\n> > +also specified.\n> \n> The above documents the status quo correctly, so let's queue, but it\n> is unfortunate that we need an extra option to do this.\n\nTrue. I didn't feel comfortable to change the default to also filter\nprovided objects when I discovered that we don't, hence the new option.\nIt's not great though as it certainly is surprising behaviour, but I'm\nnot sure whether we can really change it without breaking existing\nusers. Oh, well...\n\nIn any case, the documentation addition is very welcome, thanks!\n\nPatrick\n"},{"id":"532275","messageId":"xnstt6myzzfyq65w73xuqg7cfso3bdw6tw33shrery4e4gi2zy@pfxq2pjmb2hm","threadId":"64629","inReplyTo":"aUEUfQDJyPf6Mhtw@pks.im","subject":"Re: [PATCH] docs: clarify git-rev-list(1) --filter behavior","fromName":"Justin Tobler","fromEmail":"jltobler@gmail.com","sentAt":"2025-12-16T14:36:56Z","receivedAt":"2025-12-16T14:37:01Z","isPatch":true,"sender":{"key":"jltobler@gmail.com","avatar":"https://avatars.githubusercontent.com/u/53454972?v=4"},"body":"On 25/12/16 09:12AM, Patrick Steinhardt wrote:\n> On Tue, Dec 16, 2025 at 10:13:22AM +0900, Junio C Hamano wrote:\n> > > diff --git a/Documentation/rev-list-options.adoc b/Documentation/rev-list-options.adoc\n> > > index d9665d82c8..453ec59057 100644\n> > > --- a/Documentation/rev-list-options.adoc\n> > > +++ b/Documentation/rev-list-options.adoc\n> > > @@ -983,7 +983,9 @@ to name units in KiB, MiB, or GiB. For example, `blob:limit=1k`\n> > > is the same as 'blob:limit=1024'.\n> > > +\n> > > The form `--filter=object:type=(tag|commit|tree|blob)` omits all objects\n> > > -which are not of the requested type.\n> > > +which are not of the requested type. Note that explicitly provided objects\n> > > +ignore filters and are always printed unless `--filter-provided-objects` is\n> > > +also specified.\n> > \n> > The above documents the status quo correctly, so let's queue, but it\n> > is unfortunate that we need an extra option to do this.\n> \n> True. I didn't feel comfortable to change the default to also filter\n> provided objects when I discovered that we don't, hence the new option.\n> It's not great though as it certainly is surprising behaviour, but I'm\n> not sure whether we can really change it without breaking existing\n> users. Oh, well...\n\nOut of curiousity, are there any known use-cases where a user _would_\nwant the provided objects printed along with the filtered ones? From my\nnaive perspective it almost doesn't even sound useful and appears to\njust be a sharp edge. This maybe not worthing worrying too much about\nthough.\n\n-Justin\n"},{"id":"532278","messageId":"aUFxbDPucKr42fIJ@pks.im","threadId":"64629","inReplyTo":"xnstt6myzzfyq65w73xuqg7cfso3bdw6tw33shrery4e4gi2zy@pfxq2pjmb2hm","subject":"Re: [PATCH] docs: clarify git-rev-list(1) --filter behavior","fromName":"Patrick Steinhardt","fromEmail":"ps@pks.im","sentAt":"2025-12-16T14:49:16Z","receivedAt":"2025-12-16T14:49:23Z","isPatch":true,"sender":{"key":"ps@pks.im","avatar":"https://avatars.githubusercontent.com/u/4056630?v=4"},"body":"On Tue, Dec 16, 2025 at 08:36:56AM -0600, Justin Tobler wrote:\n> On 25/12/16 09:12AM, Patrick Steinhardt wrote:\n> > On Tue, Dec 16, 2025 at 10:13:22AM +0900, Junio C Hamano wrote:\n> > > > diff --git a/Documentation/rev-list-options.adoc b/Documentation/rev-list-options.adoc\n> > > > index d9665d82c8..453ec59057 100644\n> > > > --- a/Documentation/rev-list-options.adoc\n> > > > +++ b/Documentation/rev-list-options.adoc\n> > > > @@ -983,7 +983,9 @@ to name units in KiB, MiB, or GiB. For example, `blob:limit=1k`\n> > > > is the same as 'blob:limit=1024'.\n> > > > +\n> > > > The form `--filter=object:type=(tag|commit|tree|blob)` omits all objects\n> > > > -which are not of the requested type.\n> > > > +which are not of the requested type. Note that explicitly provided objects\n> > > > +ignore filters and are always printed unless `--filter-provided-objects` is\n> > > > +also specified.\n> > > \n> > > The above documents the status quo correctly, so let's queue, but it\n> > > is unfortunate that we need an extra option to do this.\n> > \n> > True. I didn't feel comfortable to change the default to also filter\n> > provided objects when I discovered that we don't, hence the new option.\n> > It's not great though as it certainly is surprising behaviour, but I'm\n> > not sure whether we can really change it without breaking existing\n> > users. Oh, well...\n> \n> Out of curiousity, are there any known use-cases where a user _would_\n> want the provided objects printed along with the filtered ones? From my\n> naive perspective it almost doesn't even sound useful and appears to\n> just be a sharp edge. This maybe not worthing worrying too much about\n> though.\n\nI don't really have an idea, but that's exactly the problem here.\nFilters are for example used by partial clones, and I don't want to\nbreak those because I'm not aware of some of the intricacies. Which\ndoesn't mean that there _are_ use cases where this is actually the\ndesired behaviour, but rather that there needs to be some research to\ncome to a conclusion here.\n\nPatrick\n"},{"id":"532296","messageId":"xmqqbjjy47xn.fsf@gitster.g","threadId":"64629","inReplyTo":"xnstt6myzzfyq65w73xuqg7cfso3bdw6tw33shrery4e4gi2zy@pfxq2pjmb2hm","subject":"Re: [PATCH] docs: clarify git-rev-list(1) --filter behavior","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2025-12-16T18:07:16Z","receivedAt":"2025-12-16T18:07:19Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Justin Tobler writes:\n\n>> True. I didn't feel comfortable to change the default to also filter\n>> provided objects when I discovered that we don't, hence the new option.\n>> It's not great though as it certainly is surprising behaviour, but I'm\n>> not sure whether we can really change it without breaking existing\n>> users. Oh, well...\n>\n> Out of curiousity, are there any known use-cases where a user _would_\n> want the provided objects printed along with the filtered ones? From my\n> naive perspective it almost doesn't even sound useful and appears to\n> just be a sharp edge. This maybe not worthing worrying too much about\n> though.\n\nPerhaps there is no good use case (and that is why I hinted that we\nmay want to \"fix\" it someday).\n\nIt however is understandable that nobody noticed it because for the\nprimarily intended use case of \"filter\", i.e., object transfer into\nlazy clone, you use commit-ishes to describe a range to be\nlisted/transferred, and you never filter out the commmit objects,\nperhaps?\n\n\n"}]}