docs: explain the order of output in cat-file batch operations

From: ahmed akef <[email protected]>

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

---
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(-)

index bd95a6c10a7..f1e0b4a7219 100644
@@ -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,

base-commit: 406f326d271e0bacecdb00425422c5fa3f314930

gitgitgadget

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.