cat-file: add option '-Z' that delimits input and output with NUL

[thirdparty/git.git] / Documentation / git-cat-file.txt

diff --git a/Documentation/git-cat-file.txt b/Documentation/git-cat-file.txt
index 411de2e27ddc0db762ec9be6ceec18a7fc1bf069..0e4936d182632fb3362376787efd7d633bd623d2 100644 (file)
--- a/Documentation/git-cat-file.txt
+++ b/Documentation/git-cat-file.txt
@@ -14,7 +14,7 @@ SYNOPSIS
 'git cat-file' (-t | -s) [--allow-unknown-type] <object>
 'git cat-file' (--batch | --batch-check | --batch-command) [--batch-all-objects]
             [--buffer] [--follow-symlinks] [--unordered]
-            [--textconv | --filters] [-z]
+            [--textconv | --filters] [-Z]
 'git cat-file' (--textconv | --filters)
             [<rev>:<path|tree-ish> | --path=<path|tree-ish> <rev>]
 
@@ -243,10 +243,16 @@ respectively print:
        /etc/passwd
 --
 
+-Z::
+       Only meaningful with `--batch`, `--batch-check`, or
+       `--batch-command`; input and output is NUL-delimited instead of
+       newline-delimited.
+
 -z::
        Only meaningful with `--batch`, `--batch-check`, or
        `--batch-command`; input is NUL-delimited instead of
-       newline-delimited.
+       newline-delimited. This option is deprecated in favor of
+       `-Z` as the output can otherwise be ambiguous.
 
 
 OUTPUT
@@ -384,6 +390,11 @@ notdir SP <size> LF
 is printed when, during symlink resolution, a file is used as a
 directory name.
 
+Alternatively, when `-Z` is passed, the line feeds in any of the above examples
+are replaced with NUL terminators. This ensures that output will be parsable if
+the output itself would contain a linefeed and is thus recommended for
+scripting purposes.
+
 CAVEATS
 -------