{"thread":{"id":"61986","subject":"[PATCH] docs: explain the order of output in the batched mode of git-cat-file(1)","startedAt":"2024-08-21T09:28:09Z","lastAt":"2024-08-22T19:50:35Z","messageCount":6,"participants":["ahmed akef via GitGitGadget","Junio C Hamano","Ahmed Akef"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"501409","messageId":"pull.1768.git.git.1724232485264.gitgitgadget@gmail.com","threadId":"61986","inReplyTo":null,"subject":"[PATCH] docs: explain the order of output in the batched mode of git-cat-file(1)","fromName":"ahmed akef via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2024-08-21T09:28:05Z","receivedAt":"2024-08-21T09:28:09Z","isPatch":true,"sender":{"key":"name:ahmed akef","avatar":null},"body":"From: ahmed akef \n\nThe batched mode of git-cat-file(1) reads multiple objects from stdin\nand prints their respective contents to stdout.\nThe order in which those objects are printed is not documented\nand may not be immediately obvious to the user.\nDocument it.\n\nSigned-off-by: ahmed akef \n---\n docs: explain the order of output in The batched mode of git-cat-file(1)\n \n The batched mode of git-cat-file(1) reads multiple objects from stdin\n and prints their respective contents to stdout. The order in which those\n objects are printed is not documented and may not be immediately obvious\n to the user. Document it.\n\nPublished-As: https://github.com/gitgitgadget/git/releases/tag/pr-git-1768%2Fahmedakef%2Fexplain-the-order-of-output-in-cat-file-batch-operations-v1\nFetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-git-1768/ahmedakef/explain-the-order-of-output-in-cat-file-batch-operations-v1\nPull-Request: https://github.com/git/git/pull/1768\n\n Documentation/git-cat-file.txt | 4 ++--\n 1 file changed, 2 insertions(+), 2 deletions(-)\n\ndiff --git a/Documentation/git-cat-file.txt b/Documentation/git-cat-file.txt\nindex bd95a6c10a7..f1e0b4a7219 100644\n--- a/Documentation/git-cat-file.txt\n+++ b/Documentation/git-cat-file.txt\n@@ -270,8 +270,8 @@ BATCH OUTPUT\n ------------\n \n If `--batch` or `--batch-check` is given, `cat-file` will read objects\n-from stdin, one per line, and print information about them. By default,\n-the whole line is considered as an object, as if it were fed to\n+from stdin, one per line, and print information about them sequentially in the same order.\n+By default, the whole line is considered as an object, as if it were fed to\n linkgit:git-rev-parse[1].\n \n When `--batch-command` is given, `cat-file` will read commands from stdin,\n\nbase-commit: 80ccd8a2602820fdf896a8e8894305225f86f61d\n-- \ngitgitgadget\n"},{"id":"501410","messageId":"pull.1768.v2.git.git.1724234729288.gitgitgadget@gmail.com","threadId":"61986","inReplyTo":"pull.1768.git.git.1724232485264.gitgitgadget@gmail.com","subject":"[PATCH v2] docs: explain the order of output in the batched mode of git-cat-file(1)","fromName":"ahmed akef via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2024-08-21T10:05:29Z","receivedAt":"2024-08-21T10:05:33Z","isPatch":true,"sender":{"key":"name:ahmed akef","avatar":null},"body":"From: ahmed akef \n\nThe batched mode of git-cat-file(1) reads multiple objects from stdin\nand prints their respective contents to stdout.\nThe order in which those objects are printed is not documented\nand may not be immediately obvious to the user.\nDocument it.\n\nSigned-off-by: ahmed akef \n---\n docs: explain the order of output in The batched mode of git-cat-file(1)\n \n this is the same change as https://github.com/git/git/pull/1761 but dues\n to missteps, the PR got closed and I couldn't fix it, also applied the\n review comments from @pks-t\n cc: Patrick Steinhardt ps@pks.im\n\nPublished-As: https://github.com/gitgitgadget/git/releases/tag/pr-git-1768%2Fahmedakef%2Fexplain-the-order-of-output-in-cat-file-batch-operations-v2\nFetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-git-1768/ahmedakef/explain-the-order-of-output-in-cat-file-batch-operations-v2\nPull-Request: https://github.com/git/git/pull/1768\n\nRange-diff vs v1:\n\n 1: 86a982884ec ! 1: 3f742957aa1 docs: explain the order of output in the batched mode of git-cat-file(1)\n @@ Documentation/git-cat-file.txt: BATCH OUTPUT\n If `--batch` or `--batch-check` is given, `cat-file` will read objects\n -from stdin, one per line, and print information about them. By default,\n -the whole line is considered as an object, as if it were fed to\n -+from stdin, one per line, and print information about them sequentially in the same order.\n -+By default, the whole line is considered as an object, as if it were fed to\n - linkgit:git-rev-parse[1].\n +-linkgit:git-rev-parse[1].\n ++from stdin, one per line, and print information about them in the same\n ++order as they have been read from stdin. By default, the whole line is\n ++considered as an object, as if it were fed to linkgit:git-rev-parse[1].\n \n When `--batch-command` is given, `cat-file` will read commands from stdin,\n + one per line, and print information based on the command given. With\n\n\n Documentation/git-cat-file.txt | 6 +++---\n 1 file changed, 3 insertions(+), 3 deletions(-)\n\ndiff --git a/Documentation/git-cat-file.txt b/Documentation/git-cat-file.txt\nindex bd95a6c10a7..c39074b9ee6 100644\n--- a/Documentation/git-cat-file.txt\n+++ b/Documentation/git-cat-file.txt\n@@ -270,9 +270,9 @@ BATCH OUTPUT\n ------------\n \n If `--batch` or `--batch-check` is given, `cat-file` will read objects\n-from stdin, one per line, and print information about them. By default,\n-the whole line is considered as an object, as if it were fed to\n-linkgit:git-rev-parse[1].\n+from stdin, one per line, and print information about them in the same\n+order as they have been read from stdin. By default, the whole line is\n+considered as an object, as if it were fed to linkgit:git-rev-parse[1].\n \n When `--batch-command` is given, `cat-file` will read commands from stdin,\n one per line, and print information based on the command given. With\n\nbase-commit: 80ccd8a2602820fdf896a8e8894305225f86f61d\n-- \ngitgitgadget\n"},{"id":"501446","messageId":"xmqqa5h5ztd9.fsf@gitster.g","threadId":"61986","inReplyTo":"pull.1768.v2.git.git.1724234729288.gitgitgadget@gmail.com","subject":"Re: [PATCH v2] docs: explain the order of output in the batched mode of git-cat-file(1)","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2024-08-21T17:19:14Z","receivedAt":"2024-08-21T17:19:19Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"ahmed akef via GitGitGadget\" writes:\n\n> If `--batch` or `--batch-check` is given, `cat-file` will read objects\n> -from stdin, one per line, and print information about them. By default,\n> -the whole line is considered as an object, as if it were fed to\n> -linkgit:git-rev-parse[1].\n> +from stdin, one per line, and print information about them in the same\n> +order as they have been read from stdin. By default, the whole line is\n> +considered as an object, as if it were fed to linkgit:git-rev-parse[1].\n\nA few \"Huh?\" I had while reading the above.\n\n * \"as they have been read from stdin\"; drop \"from stdin\" here, as\n we already know we are talking about the mode that reads object\n names from the standard input and there is no need to repeat it.\n\n * \"considered as an object\" -> \"considered to be an object name\" or\n \"used as an object name\" [*]. This primarily comes from my\n spinal reflex against \"consider as\", plus my desire to be more\n precise in terminology.\n\nThanks.\n\nNothing mentioned below should be part of this patch, but as I\nnoticed it while studying the current documentation to prepare this\nreview, I'll record them as #leftoverbits.\n\nThe description of how lines read from the standard input should\nlook like needs more work. Documentation on \"--batch\" says \"the\ninput lines must specify the path, separated by whitespace\", but is\nit clear that it expects \"\", followed by a whitespace\n(not necessarily a single SP), followed by \"\"? Without prior\nknowledge, I wouldn't be surprised if somebody read the text as\nasking for paths separated by whitespace, e.g.\n\n README.txt COPYING Makefile\n\nthat gives three paths. The text needs to be tightened to say\nsomething like \"must give the path after the object name, separated\nby whitespace. The path is used to find the textconv and smudge\nfilter\".\n\nThe section also says \"See the section BATCH OUTPUT below for\ndetails.\" but the section it refers to does not talk anything about\nthis whitespace thing. It also is unclear what would happen if the\ninput line says:\n\n :COPYING Makefile\n\nWould it apply the textconv/filters meant for Makefile to the blob\nstored at COPYING in the index? If we say\n\n :README.txt\n \nwould the command be smart enough to know that the blob came from\nthe path README.txt and apply the textconv/filters meant for that\npath, without the input repeating the same information twice like:\n\n :README.txt README.txt\n\nor something silly like that?\n\n\n[Reference]\n\n* https://www.britannica.com/dictionary/eb/qa/consider-and-consider-as\n\n\n"},{"id":"501490","messageId":"CAH64z8Ji59amg5Y=cBJzFKt_XiB0A5re35g9jHPWS6AoyGpRWw@mail.gmail.com","threadId":"61986","inReplyTo":"CAH64z8KUWSNii_U5k5fAz3q9cu34+pOWk2Rmw-60x7iOKOD8gQ@mail.gmail.com","subject":"Re: [PATCH v2] docs: explain the order of output in the batched mode of git-cat-file(1)","fromName":"Ahmed Akef","fromEmail":"aemed.akef.1@gmail.com","sentAt":"2024-08-22T07:31:57Z","receivedAt":"2024-08-22T07:32:34Z","isPatch":true,"sender":{"key":"aemed.akef.1@gmail.com","avatar":null},"body":"> * \"as they have been read from stdin\"; drop \"from stdin\" here, as\n> we already know we are talking about the mode that reads object\n> names from the standard input and there is no need to repeat it.\n\nit is needed to explain that git will not do any optimization to the\norder of paths\nbefore printing the output. I entered a discussion with someone who was worried\nthat git may optimize the paths order because it is not stated clearly\nthat output follows\nthe same order as input.\n\n> * \"considered as an object\" -> \"considered to be an object name\" or\n> \"used as an object name\" [*]. This primarily comes from my\n> spinal reflex against \"consider as\", plus my desire to be more\n> precise in terminology.\n\nthis is not related to my changes, I just moved this line but didn't change it.\n\n\nThanks,\nahmed akef\n\n\nThanks,\nahmed akef\n\n\nOn Thu, Aug 22, 2024 at 9:20 AM Ahmed Akef wrote:\n>\n> > * \"as they have been read from stdin\"; drop \"from stdin\" here, as\n> > we already know we are talking about the mode that reads object\n> > names from the standard input and there is no need to repeat it.\n>\n> it is needed to explain that git will not do any optimization to the order of paths\n> before printing the output. I entered a discussion with someone who was worried\n> that git may optimize the paths order because it is not stated clearly that output follows\n> the same order as input.\n>\n> > * \"considered as an object\" -> \"considered to be an object name\" or\n> > \"used as an object name\" [*]. This primarily comes from my\n> > spinal reflex against \"consider as\", plus my desire to be more\n> > precise in terminology.\n>\n> this is not related to my changes, I just moved this line but didn't changed it.\n>\n> Thanks,\n> ahmed akef\n>\n>\n> On Thu, Aug 22, 2024 at 9:18 AM Ahmed Akef wrote:\n>>\n>> > * \"as they have been read from stdin\"; drop \"from stdin\" here, as\n>> > we already know we are talking about the mode that reads object\n>> > names from the standard input and there is no need to repeat it.\n>>\n>> it is needed to explain that git will not do any optimization to the order of paths\n>> before printing the output. I entered a discussion with someone who was worried\n>> that git may optimize the paths order because it is not stated clearly that output follows\n>> the same order as input.\n>>\n>> > * \"considered as an object\" -> \"considered to be an object name\" or\n>> > \"used as an object name\" [*]. This primarily comes from my\n>> > spinal reflex against \"consider as\", plus my desire to be more\n>> > precise in terminology.\n>>\n>> this is not related to my changes, I just moved this line but didn't changed it.\n>>\n>> Thanks,\n>> ahmed akef\n>>\n>>\n>> On Wed, Aug 21, 2024 at 7:19 PM Junio C Hamano wrote:\n>>>\n>>> \"ahmed akef via GitGitGadget\" writes:\n>>>\n>>> > If `--batch` or `--batch-check` is given, `cat-file` will read objects\n>>> > -from stdin, one per line, and print information about them. By default,\n>>> > -the whole line is considered as an object, as if it were fed to\n>>> > -linkgit:git-rev-parse[1].\n>>> > +from stdin, one per line, and print information about them in the same\n>>> > +order as they have been read from stdin. By default, the whole line is\n>>> > +considered as an object, as if it were fed to linkgit:git-rev-parse[1].\n>>>\n>>> A few \"Huh?\" I had while reading the above.\n>>>\n>>> * \"as they have been read from stdin\"; drop \"from stdin\" here, as\n>>> we already know we are talking about the mode that reads object\n>>> names from the standard input and there is no need to repeat it.\n>>>\n>>> * \"considered as an object\" -> \"considered to be an object name\" or\n>>> \"used as an object name\" [*]. This primarily comes from my\n>>> spinal reflex against \"consider as\", plus my desire to be more\n>>> precise in terminology.\n>>>\n>>> Thanks.\n>>>\n>>> Nothing mentioned below should be part of this patch, but as I\n>>> noticed it while studying the current documentation to prepare this\n>>> review, I'll record them as #leftoverbits.\n>>>\n>>> The description of how lines read from the standard input should\n>>> look like needs more work. Documentation on \"--batch\" says \"the\n>>> input lines must specify the path, separated by whitespace\", but is\n>>> it clear that it expects \"\", followed by a whitespace\n>>> (not necessarily a single SP), followed by \"\"? Without prior\n>>> knowledge, I wouldn't be surprised if somebody read the text as\n>>> asking for paths separated by whitespace, e.g.\n>>>\n>>> README.txt COPYING Makefile\n>>>\n>>> that gives three paths. The text needs to be tightened to say\n>>> something like \"must give the path after the object name, separated\n>>> by whitespace. The path is used to find the textconv and smudge\n>>> filter\".\n>>>\n>>> The section also says \"See the section BATCH OUTPUT below for\n>>> details.\" but the section it refers to does not talk anything about\n>>> this whitespace thing. It also is unclear what would happen if the\n>>> input line says:\n>>>\n>>> :COPYING Makefile\n>>>\n>>> Would it apply the textconv/filters meant for Makefile to the blob\n>>> stored at COPYING in the index? If we say\n>>>\n>>> :README.txt\n>>>\n>>> would the command be smart enough to know that the blob came from\n>>> the path README.txt and apply the textconv/filters meant for that\n>>> path, without the input repeating the same information twice like:\n>>>\n>>> :README.txt README.txt\n>>>\n>>> or something silly like that?\n>>>\n>>>\n>>> [Reference]\n>>>\n>>> * https://www.britannica.com/dictionary/eb/qa/consider-and-consider-as\n>>>\n>>>\n"},{"id":"501538","messageId":"xmqqv7zsvbod.fsf@gitster.g","threadId":"61986","inReplyTo":"CAH64z8Ji59amg5Y=cBJzFKt_XiB0A5re35g9jHPWS6AoyGpRWw@mail.gmail.com","subject":"Re: [PATCH v2] docs: explain the order of output in the batched mode of git-cat-file(1)","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2024-08-22T15:07:14Z","receivedAt":"2024-08-22T15:07:26Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Ahmed Akef writes:\n\nAdministrivia: please do not break the discussion thread by dropping\nIn-Reply-To: and / or References: headers. For those who are\nfollowing from sidelines, this is a reponse to\n\n https://lore.kernel.org/git/xmqqa5h5ztd9.fsf@gitster.g/\n\n>> * \"as they have been read from stdin\"; drop \"from stdin\" here, as\n>> we already know we are talking about the mode that reads object\n>> names from the standard input and there is no need to repeat it.\n>\n> it is needed to explain that git will not do any optimization to the\n> order of paths\n> before printing the output.\n\nI do not think \"from stdin\" is necessary for that. The sentence\nbegins ...\n\n> If `--batch` or `--batch-check` is given, `cat-file` will read objects\n> +from stdin, one per line, and print information about them in the same\n> +order as they have been read from stdin. By default, the whole line is\n> +considered as an object, as if it were fed to linkgit:git-rev-parse[1].\n\n... by explaining that the command reads from the standard input, and\ndoes something to each in the same order as they were read. If you\nalready said you are reading from the standard input, the order you\nread them is the order youread them from the standard input.\n\nDrop the \"from stdin\" from \"as they have been read from stdin\".\n"},{"id":"501560","messageId":"pull.1768.v3.git.git.1724356231639.gitgitgadget@gmail.com","threadId":"61986","inReplyTo":"pull.1768.v2.git.git.1724234729288.gitgitgadget@gmail.com","subject":"[PATCH v3] docs: explain the order of output in the batched mode of git-cat-file(1)","fromName":"ahmed akef via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2024-08-22T19:50:31Z","receivedAt":"2024-08-22T19:50:35Z","isPatch":true,"sender":{"key":"name:ahmed akef","avatar":null},"body":"From: ahmed akef \n\nThe batched mode of git-cat-file(1) reads multiple objects from stdin\nand prints their respective contents to stdout.\nThe order in which those objects are printed is not documented\nand may not be immediately obvious to the user.\nDocument it.\n\nSigned-off-by: ahmed akef \n---\n docs: explain the order of output in The batched mode of git-cat-file(1)\n \n this is the same change as https://github.com/git/git/pull/1761 but due\n to missteps, the PR got closed and I couldn't fix it, also applied the\n review comments from @pks-t\n cc: Patrick Steinhardt ps@pks.im\n\nPublished-As: https://github.com/gitgitgadget/git/releases/tag/pr-git-1768%2Fahmedakef%2Fexplain-the-order-of-output-in-cat-file-batch-operations-v3\nFetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-git-1768/ahmedakef/explain-the-order-of-output-in-cat-file-batch-operations-v3\nPull-Request: https://github.com/git/git/pull/1768\n\nRange-diff vs v2:\n\n 1: 3f742957aa1 ! 1: 6adeb2c7bb3 docs: explain the order of output in the batched mode of git-cat-file(1)\n @@ Documentation/git-cat-file.txt: BATCH OUTPUT\n -the whole line is considered as an object, as if it were fed to\n -linkgit:git-rev-parse[1].\n +from stdin, one per line, and print information about them in the same\n -+order as they have been read from stdin. By default, the whole line is\n ++order as they have been read. By default, the whole line is\n +considered as an object, as if it were fed to linkgit:git-rev-parse[1].\n \n When `--batch-command` is given, `cat-file` will read commands from stdin,\n\n\n Documentation/git-cat-file.txt | 6 +++---\n 1 file changed, 3 insertions(+), 3 deletions(-)\n\ndiff --git a/Documentation/git-cat-file.txt b/Documentation/git-cat-file.txt\nindex bd95a6c10a7..d5890ae3686 100644\n--- a/Documentation/git-cat-file.txt\n+++ b/Documentation/git-cat-file.txt\n@@ -270,9 +270,9 @@ BATCH OUTPUT\n ------------\n \n If `--batch` or `--batch-check` is given, `cat-file` will read objects\n-from stdin, one per line, and print information about them. By default,\n-the whole line is considered as an object, as if it were fed to\n-linkgit:git-rev-parse[1].\n+from stdin, one per line, and print information about them in the same\n+order as they have been read. By default, the whole line is\n+considered as an object, as if it were fed to linkgit:git-rev-parse[1].\n \n When `--batch-command` is given, `cat-file` will read commands from stdin,\n one per line, and print information based on the command given. With\n\nbase-commit: 80ccd8a2602820fdf896a8e8894305225f86f61d\n-- \ngitgitgadget\n"}]}