cat-file: add --batch-command mode

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

diff --git a/Documentation/git-cat-file.txt b/Documentation/git-cat-file.txt
index bef76f4dd060dd7fdd4efee44f53b34a3c546c13..70c5b4f12d1a9d22dcb53c6b9d12db0530559aee 100644 (file)
--- a/Documentation/git-cat-file.txt
+++ b/Documentation/git-cat-file.txt
@@ -96,6 +96,33 @@ OPTIONS
        need to specify the path, separated by whitespace.  See the
        section `BATCH OUTPUT` below for details.
 
+--batch-command::
+--batch-command=<format>::
+       Enter a command mode that reads commands and arguments from stdin. May
+       only be combined with `--buffer`, `--textconv` or `--filters`. In the
+       case of `--textconv` or `--filters`, the input lines also need to specify
+       the path, separated by whitespace. See the section `BATCH OUTPUT` below
+       for details.
++
+`--batch-command` recognizes the following commands:
++
+--
+contents <object>::
+       Print object contents for object reference `<object>`. This corresponds to
+       the output of `--batch`.
+
+info <object>::
+       Print object info for object reference `<object>`. This corresponds to the
+       output of `--batch-check`.
+
+flush::
+       Used with `--buffer` to execute all preceding commands that were issued
+       since the beginning or since the last flush was issued. When `--buffer`
+       is used, no output will come until a `flush` is issued. When `--buffer`
+       is not used, commands are flushed each time without issuing `flush`.
+--
++
+
 --batch-all-objects::
        Instead of reading a list of objects on stdin, perform the
        requested batch operation on all objects in the repository and
@@ -110,7 +137,7 @@ OPTIONS
        that a process can interactively read and write from
        `cat-file`. With this option, the output uses normal stdio
        buffering; this is much more efficient when invoking
-       `--batch-check` on a large number of objects.
+       `--batch-check` or `--batch-command` on a large number of objects.
 
 --unordered::
        When `--batch-all-objects` is in use, visit objects in an
@@ -202,6 +229,13 @@ 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
 linkgit:git-rev-parse[1].
 
+When `--batch-command` is given, `cat-file` will read commands from stdin,
+one per line, and print information based on the command given. With
+`--batch-command`, the `info` command followed by an object will print
+information about the object the same way `--batch-check` would, and the
+`contents` command followed by an object prints contents in the same way
+`--batch` would.
+
 You can specify the information shown for each object by using a custom
 `<format>`. The `<format>` is copied literally to stdout for each
 object, with placeholders of the form `%(atom)` expanded, followed by a
@@ -237,9 +271,9 @@ newline. The available atoms are:
 If no format is specified, the default format is `%(objectname)
 %(objecttype) %(objectsize)`.
 
-If `--batch` is specified, the object information is followed by the
-object contents (consisting of `%(objectsize)` bytes), followed by a
-newline.
+If `--batch` is specified, or if `--batch-command` is used with the `contents`
+command, the object information is followed by the object contents (consisting
+of `%(objectsize)` bytes), followed by a newline.
 
 For example, `--batch` without a custom format would produce: