[PATCH] doc/cat-file: clarify description regarding various command forms

From: Štěpán Němec <stepnem@smrk.net>
Date: Oct 3, 2023, 08:25 UTC
Message-ID: <20231003082513.3003520-1-stepnem@smrk.net>

The DESCRIPTION's "first form" is actually the 1st, 2nd, 3rd and 5th form in SYNOPSIS, the "second form" is the 4th one.

Interestingly, this state of affairs was introduced in 97fe7250753b (cat-file docs: fix SYNOPSIS and "-h" output, 2021-12-28) with the claim of "Now the two will match again." ("the two" being DESCRIPTION and SYNOPSIS)...

Ordinals are hard, let's try talking about batch and non-batch mode instead.

Signed-off-by: Štěpán Němec <stepnem@smrk.net>
---
 Documentation/git-cat-file.txt | 7 +++++--
 1 file changed, 5 insertions(+), 2 deletions(-)

diff --git a/Documentation/git-cat-file.txt b/Documentation/git-cat-file.txt
index 0e4936d18263..1957f90335a4 100644
--- a/Documentation/git-cat-file.txt
+++ b/Documentation/git-cat-file.txt
@@ -20,12 +20,15 @@ SYNOPSIS
 
 DESCRIPTION
 -----------
-In its first form, the command provides the content or the type of an object in
+This command can operate in two modes, depending on whether an option from
+the `--batch` family is specified.
+
+In non-batch mode, the command provides the content or the type of an object in
 the repository. The type is required unless `-t` or `-p` is used to find the
 object type, or `-s` is used to find the object size, or `--textconv` or
 `--filters` is used (which imply type "blob").
 
-In the second form, a list of objects (separated by linefeeds) is provided on
+In batch mode, a list of objects (separated by linefeeds) is provided on
 stdin, and the SHA-1, type, and size of each object is printed on stdout. The
 output format can be overridden using the optional `<format>` argument. If
 either `--textconv` or `--filters` was specified, the input is expected to

base-commit: d0e8084c65cbf949038ae4cc344ac2c2efd77415

-- 
2.42.0