{"thread":{"id":"61974","subject":"[PATCH] docs: explain the order of output in cat-file batch operations","startedAt":"2024-08-19T12:26:54Z","lastAt":"2024-08-21T07:00:28Z","messageCount":2,"participants":["ahmed akef via GitGitGadget","Patrick Steinhardt"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"501268","messageId":"pull.1761.git.git.1724070410906.gitgitgadget@gmail.com","threadId":"61974","inReplyTo":null,"subject":"[PATCH] docs: explain the order of output in cat-file batch operations","fromName":"ahmed akef via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2024-08-19T12:26:50Z","receivedAt":"2024-08-19T12:26:54Z","isPatch":true,"sender":{"key":"name:ahmed akef","avatar":null},"body":"From: ahmed akef <aemed.akef.1@gmail.com>\n\nthe order of the output is not described explicitly so someone can make\ncomplex code to parse it instead of just depending on the order\n\nSigned-off-by: ahmed akef <aemed.akef.1@gmail.com>\n---\n    explain the order of output in cat-file batch operations since it is not\n    explicit\n\nPublished-As: https://github.com/gitgitgadget/git/releases/tag/pr-git-1761%2Fahmedakef%2Fexplain-the-order-of-output-in-cat-file-batch-operations-v1\nFetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-git-1761/ahmedakef/explain-the-order-of-output-in-cat-file-batch-operations-v1\nPull-Request: https://github.com/git/git/pull/1761\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: 406f326d271e0bacecdb00425422c5fa3f314930\n-- \ngitgitgadget\n"},{"id":"501405","messageId":"ZsWQgYclF4ahQPrQ@tanuki","threadId":"61974","inReplyTo":"pull.1761.git.git.1724070410906.gitgitgadget@gmail.com","subject":"Re: [PATCH] docs: explain the order of output in cat-file batch operations","fromName":"Patrick Steinhardt","fromEmail":"ps@pks.im","sentAt":"2024-08-21T07:00:24Z","receivedAt":"2024-08-21T07:00:28Z","isPatch":true,"sender":{"key":"ps@pks.im","avatar":"https://avatars.githubusercontent.com/u/4056630?v=4"},"body":"On Mon, Aug 19, 2024 at 12:26:50PM +0000, ahmed akef via GitGitGadget wrote:\n> From: ahmed akef <aemed.akef.1@gmail.com>\n> \n> the order of the output is not described explicitly so someone can make\n> complex code to parse it instead of just depending on the order\n\nWe aim to write full sentences in commit messages. That is, they start\nwith an upper-case letter and should end with some form of punctuation.\nIt's also not immediately clear what \"the output\" refers to without\nreferring to the subject. And last but not least, it could use some\nexplanation that this all refers to the `--batch` mode, only.\n\nI would have probably written something like this:\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\n  those objects are printed is not documented and may not be immediately\n  obvious to the user. Document it.\n\nThis explains the context, proceeds to the problem and then says how we\naddress the problem.\n\n> Signed-off-by: ahmed akef <aemed.akef.1@gmail.com>\n> ---\n>     explain the order of output in cat-file batch operations since it is not\n>     explicit\n> \n> Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-git-1761%2Fahmedakef%2Fexplain-the-order-of-output-in-cat-file-batch-operations-v1\n> Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-git-1761/ahmedakef/explain-the-order-of-output-in-cat-file-batch-operations-v1\n> Pull-Request: https://github.com/git/git/pull/1761\n> \n>  Documentation/git-cat-file.txt | 4 ++--\n>  1 file changed, 2 insertions(+), 2 deletions(-)\n> \n> diff --git a/Documentation/git-cat-file.txt b/Documentation/git-cat-file.txt\n> index 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\nThese lines are now overly long. We should likely wrap them at 72\ncharacters.\n\nI'd likely also replace \"sequentially in the same order\" with \"in the\nsame order as they have been read from stdin\", which feels a bit more\nexplicit to me.\n\nThanks!\n\nPatrick\n"}]}