Merge branch 'maint-1.7.7' into maint-1.7.8

[git.git] / Documentation / git-fast-import.txt

diff --git a/Documentation/git-fast-import.txt b/Documentation/git-fast-import.txt
index 95e480ef7968af9d3bb055e8fd9750b08d620622..ec6ef3119792a9e66a3a46bf6f0754458ea6a061 100644 (file)
--- a/Documentation/git-fast-import.txt
+++ b/Documentation/git-fast-import.txt
@@ -102,6 +102,12 @@ OPTIONS
        when the `cat-blob` command is encountered in the stream.
        The default behaviour is to write to `stdout`.
 
        when the `cat-blob` command is encountered in the stream.
        The default behaviour is to write to `stdout`.
 

+--done::
+       Require a `done` command at the end of the stream.
+       This option might be useful for detecting errors that
+       cause the frontend to terminate before it has started to
+       write a stream.
+

 --export-pack-edges=<file>::
        After creating a packfile, print a line of data to
        <file> listing the filename of the packfile and the last
 --export-pack-edges=<file>::
        After creating a packfile, print a line of data to
        <file> listing the filename of the packfile and the last


@@ -331,6 +337,11 @@ and control the current import process.  More detailed discussion
        standard output.  This command is optional and is not needed
        to perform an import.
 
        standard output.  This command is optional and is not needed
        to perform an import.
 

+`done`::
+       Marks the end of the stream. This command is optional
+       unless the `done` feature was requested using the
+       `--done` command line option or `feature done` command.
+

 `cat-blob`::
        Causes fast-import to print a blob in 'cat-file --batch'
        format to the file descriptor set with `--cat-blob-fd` or
 `cat-blob`::
        Causes fast-import to print a blob in 'cat-file --batch'
        format to the file descriptor set with `--cat-blob-fd` or


@@ -414,8 +425,8 @@ Here `<name>` is the person's display name (for example
 (``cm@example.com'').  `LT` and `GT` are the literal less-than (\x3c)
 and greater-than (\x3e) symbols.  These are required to delimit
 the email address from the other fields in the line.  Note that
 (``cm@example.com'').  `LT` and `GT` are the literal less-than (\x3c)
 and greater-than (\x3e) symbols.  These are required to delimit
 the email address from the other fields in the line.  Note that

-`<name>` is free-form and may contain any sequence of bytes, except
-`LT` and `LF`.  It is typically UTF-8 encoded.
+`<name>` and `<email>` are free-form and may contain any sequence
+of bytes, except `LT`, `GT` and `LF`.  `<name>` is typically UTF-8 encoded.

 
 The time of the change is specified by `<when>` using the date format
 that was selected by the \--date-format=<fmt> command line option.
 
 The time of the change is specified by `<when>` using the date format
 that was selected by the \--date-format=<fmt> command line option.


@@ -1001,10 +1012,14 @@ force::
        (see OPTIONS, above).
 
 import-marks::
        (see OPTIONS, above).
 
 import-marks::

+import-marks-if-exists::

        Like --import-marks except in two respects: first, only one
        Like --import-marks except in two respects: first, only one

-       "feature import-marks" command is allowed per stream;
-       second, an --import-marks= command-line option overrides
-       any "feature import-marks" command in the stream.
+       "feature import-marks" or "feature import-marks-if-exists"
+       command is allowed per stream; second, an --import-marks=
+       or --import-marks-if-exists command-line option overrides
+       any of these "feature" commands in the stream; third,
+       "feature import-marks-if-exists" like a corresponding
+       command-line option silently skips a nonexistent file.

 
 cat-blob::
 ls::
 
 cat-blob::
 ls::


@@ -1021,6 +1036,11 @@ notes::
        Versions of fast-import not supporting notes will exit
        with a message indicating so.
 
        Versions of fast-import not supporting notes will exit
        with a message indicating so.
 

+done::
+       Error out if the stream ends without a 'done' command.
+       Without this feature, errors causing the frontend to end
+       abruptly at a convenient point in the stream can go
+       undetected.

 
 `option`
 ~~~~~~~~
 
 `option`
 ~~~~~~~~


@@ -1050,6 +1070,15 @@ not be passed as option:
 * cat-blob-fd
 * force
 
 * cat-blob-fd
 * force
 

+`done`
+~~~~~~
+If the `done` feature is not in use, treated as if EOF was read.
+This can be used to tell fast-import to finish early.
+
+If the `--done` command line option or `feature done` command is
+in use, the `done` command is mandatory and marks the end of the
+stream.
+

 Crash Reports
 -------------
 If fast-import is supplied invalid input it will terminate with a
 Crash Reports
 -------------
 If fast-import is supplied invalid input it will terminate with a