tag.c: implement '--format' option

diff --git a/Documentation/git-fast-import.txt b/Documentation/git-fast-import.txt
index fd328952556fc8a28db72e6537595067aadbd946..66910aa2faff1d78b71c5c552550a4f8e9d51832 100644 (file)
--- a/Documentation/git-fast-import.txt
+++ b/Documentation/git-fast-import.txt
@@ -54,7 +54,7 @@ Options for Frontends
 ~~~~~~~~~~~~~~~~~~~~~
 
 --cat-blob-fd=<fd>::
-       Write responses to `cat-blob` and `ls` queries to the
+       Write responses to `get-mark`, `cat-blob`, and `ls` queries to the
        file descriptor <fd> instead of `stdout`.  Allows `progress`
        output intended for the end-user to be separated from other
        output.
@@ -350,6 +350,11 @@ and control the current import process.  More detailed discussion
        unless the `done` feature was requested using the
        `--done` command-line option or `feature done` command.
 
+`get-mark`::
+       Causes fast-import to print the SHA-1 corresponding to a mark
+       to the file descriptor set with `--cat-blob-fd`, or `stdout` if
+       unspecified.
+
 `cat-blob`::
        Causes fast-import to print a blob in 'cat-file --batch'
        format to the file descriptor set with `--cat-blob-fd` or
@@ -930,6 +935,25 @@ Placing a `progress` command immediately after a `checkpoint` will
 inform the reader when the `checkpoint` has been completed and it
 can safely access the refs that fast-import updated.
 
+`get-mark`
+~~~~~~~~~~
+Causes fast-import to print the SHA-1 corresponding to a mark to
+stdout or to the file descriptor previously arranged with the
+`--cat-blob-fd` argument. The command otherwise has no impact on the
+current import; its purpose is to retrieve SHA-1s that later commits
+might want to refer to in their commit messages.
+
+....
+       'get-mark' SP ':' <idnum> LF
+....
+
+This command can be used anywhere in the stream that comments are
+accepted.  In particular, the `get-mark` command can be used in the
+middle of a commit but not in the middle of a `data` command.
+
+See ``Responses To Commands'' below for details about how to read
+this output safely.
+
 `cat-blob`
 ~~~~~~~~~~
 Causes fast-import to print a blob to a file descriptor previously
@@ -1000,7 +1024,8 @@ Output uses the same format as `git ls-tree <tree> -- <path>`:
 ====
 
 The <dataref> represents the blob, tree, or commit object at <path>
-and can be used in later 'cat-blob', 'filemodify', or 'ls' commands.
+and can be used in later 'get-mark', 'cat-blob', 'filemodify', or
+'ls' commands.
 
 If there is no file or subtree at that path, 'git fast-import' will
 instead report
@@ -1042,9 +1067,11 @@ import-marks-if-exists::
        "feature import-marks-if-exists" like a corresponding
        command-line option silently skips a nonexistent file.
 
+get-mark::
 cat-blob::
 ls::
-       Require that the backend support the 'cat-blob' or 'ls' command.
+       Require that the backend support the 'get-mark', 'cat-blob',
+       or 'ls' command respectively.
        Versions of fast-import not supporting the specified command
        will exit with a message indicating so.
        This lets the import error out early with a clear message,
@@ -1124,11 +1151,11 @@ bidirectional pipes:
        git fast-import >fast-import-output
 ====
 
-A frontend set up this way can use `progress`, `ls`, and `cat-blob`
-commands to read information from the import in progress.
+A frontend set up this way can use `progress`, `get-mark`, `ls`, and
+`cat-blob` commands to read information from the import in progress.
 
 To avoid deadlock, such frontends must completely consume any
-pending output from `progress`, `ls`, and `cat-blob` before
+pending output from `progress`, `ls`, `get-mark`, and `cat-blob` before
 performing writes to fast-import that might block.
 
 Crash Reports