| Message ID | pull.1761.git.git.1724070410906.gitgitgadget@gmail.com (mailing list archive) |
|---|---|
| State | New |
| Headers | show |
| Series | docs: explain the order of output in cat-file batch operations | expand |
On Mon, Aug 19, 2024 at 12:26:50PM +0000, ahmed akef via GitGitGadget wrote: > From: ahmed akef <aemed.akef.1@gmail.com> > > the order of the output is not described explicitly so someone can make > complex code to parse it instead of just depending on the order We aim to write full sentences in commit messages. That is, they start with an upper-case letter and should end with some form of punctuation. It's also not immediately clear what "the output" refers to without referring to the subject. And last but not least, it could use some explanation that this all refers to the `--batch` mode, only. I would have probably written something like this: The batched mode of git-cat-file(1) reads multiple objects from stdin and prints their respective contents to stdout. The order in which those objects are printed is not documented and may not be immediately obvious to the user. Document it. This explains the context, proceeds to the problem and then says how we address the problem. > Signed-off-by: ahmed akef <aemed.akef.1@gmail.com> > --- > explain the order of output in cat-file batch operations since it is not > explicit > > Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-git-1761%2Fahmedakef%2Fexplain-the-order-of-output-in-cat-file-batch-operations-v1 > 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 > Pull-Request: https://github.com/git/git/pull/1761 > > Documentation/git-cat-file.txt | 4 ++-- > 1 file changed, 2 insertions(+), 2 deletions(-) > > diff --git a/Documentation/git-cat-file.txt b/Documentation/git-cat-file.txt > index bd95a6c10a7..f1e0b4a7219 100644 > --- a/Documentation/git-cat-file.txt > +++ b/Documentation/git-cat-file.txt > @@ -270,8 +270,8 @@ BATCH OUTPUT > ------------ > > If `--batch` or `--batch-check` is given, `cat-file` will read objects > -from stdin, one per line, and print information about them. By default, > -the whole line is considered as an object, as if it were fed to > +from stdin, one per line, and print information about them sequentially in the same order. > +By default, the whole line is considered as an object, as if it were fed to These lines are now overly long. We should likely wrap them at 72 characters. I'd likely also replace "sequentially in the same order" with "in the same order as they have been read from stdin", which feels a bit more explicit to me. Thanks! Patrick
diff --git a/Documentation/git-cat-file.txt b/Documentation/git-cat-file.txt index bd95a6c10a7..f1e0b4a7219 100644 --- a/Documentation/git-cat-file.txt +++ b/Documentation/git-cat-file.txt @@ -270,8 +270,8 @@ BATCH OUTPUT ------------ If `--batch` or `--batch-check` is given, `cat-file` will read objects -from stdin, one per line, and print information about them. By default, -the whole line is considered as an object, as if it were fed to +from stdin, one per line, and print information about them sequentially in the same order. +By default, the whole line is considered as an object, as if it were fed to linkgit:git-rev-parse[1]. When `--batch-command` is given, `cat-file` will read commands from stdin,