Autogenerated HTML docs for v1.5.3-rc5-40-g2f82

1 files changed, 70 insertions, 4 deletions

diff --git a/git-fast-import.txt b/git-fast-import.txt
index 30ee98d17..0a019dd2e 100644
--- a/git-fast-import.txt
+++ b/git-fast-import.txt
@@ -176,6 +176,15 @@ results, such as branch names or file names with leading or trailing
 spaces in their name, or early termination of fast-import when it encounters
 unexpected input.
 
+Stream Comments
+~~~~~~~~~~~~~~~
+To aid in debugging frontends fast-import ignores any line that
+begins with `#` (ASCII pound/hash) up to and including the line
+ending `LF`.  A comment line may contain any sequence of bytes
+that does not contain an LF and therefore may be used to include
+any detailed debugging information that might be specific to the
+frontend and useful when inspecting a fast-import data stream.
+
 Date Formats
 ~~~~~~~~~~~~
 The following date formats are supported.  A frontend should select
@@ -289,6 +298,11 @@ and control the current import process.  More detailed discussion
 	This command is optional and is not needed to perform
 	an import.
 
+`progress`::
+	Causes fast-import to echo the entire line to its own
+	standard output.  This command is optional and is not needed
+	to perform an import.
+
 `commit`
 ~~~~~~~~
 Create or update a branch with a new commit, recording one logical
@@ -303,7 +317,7 @@ change to the project.
 	('from' SP <committish> LF)?
 	('merge' SP <committish> LF)?
 	(filemodify | filedelete | filecopy | filerename | filedeleteall)*
-	LF
+	LF?
 ....
 
 where `<ref>` is the name of the branch to make the commit on.
@@ -334,6 +348,8 @@ all `filemodify`, `filecopy` and `filerename` commands in the same
 commit, as `filedeleteall`
 wipes the branch clean (see below).
 
+The `LF` after the command is optional (it used to be required).
+
 `author`
 ^^^^^^^^
 An `author` command may optionally appear, if the author information
@@ -645,12 +661,14 @@ branch from an existing commit without creating a new commit.
 ....
 	'reset' SP <ref> LF
 	('from' SP <committish> LF)?
-	LF
+	LF?
 ....
 
 For a detailed description of `<ref>` and `<committish>` see above
 under `commit` and `from`.
 
+The `LF` after the command is optional (it used to be required).
+
 The `reset` command can also be used to create lightweight
 (non-annotated) tags.  For example:
 
@@ -689,18 +707,28 @@ intended for production-quality conversions should always use the
 exact byte count format, as it is more robust and performs better.
 The delimited format is intended primarily for testing fast-import.
 
+Comment lines appearing within the `<raw>` part of `data` commands
+are always taken to be part of the body of the data and are therefore
+never ignored by fast-import.  This makes it safe to import any
+file/message content whose lines might start with `#`.
+
 Exact byte count format::
 	The frontend must specify the number of bytes of data.
 +
 ....
 	'data' SP <count> LF
-	<raw> LF
+	<raw> LF?
 ....
 +
 where `<count>` is the exact number of bytes appearing within
 `<raw>`.  The value of `<count>` is expressed as an ASCII decimal
 integer.  The `LF` on either side of `<raw>` is not
 included in `<count>` and will not be included in the imported data.
++
+The `LF` after `<raw>` is optional (it used to be required) but
+recommended.  Always including it makes debugging a fast-import
+stream easier as the next command always starts in column 0
+of the next line, even if `<raw>` did not end with an `LF`.
 
 Delimited format::
 	A delimiter string is used to mark the end of the data.
@@ -712,6 +740,7 @@ Delimited format::
 	'data' SP '<<' <delim> LF
 	<raw> LF
 	<delim> LF
+	LF?
 ....
 +
 where `<delim>` is the chosen delimiter string.  The string `<delim>`
@@ -720,6 +749,8 @@ fast-import will think the data ends earlier than it really does.  The `LF`
 immediately trailing `<raw>` is part of `<raw>`.  This is one of
 the limitations of the delimited format, it is impossible to supply
 a data chunk which does not have an LF as its last byte.
++
+The `LF` after `<delim> LF` is optional (it used to be required).
 
 `checkpoint`
 ~~~~~~~~~~~~
@@ -728,7 +759,7 @@ save out all current branch refs, tags and marks.
 
 ....
 	'checkpoint' LF
-	LF
+	LF?
 ....
 
 Note that fast-import automatically switches packfiles when the current
@@ -747,6 +778,32 @@ process access to a branch.  However given that a 30 GiB Subversion
 repository can be loaded into Git through fast-import in about 3 hours,
 explicit checkpointing may not be necessary.
 
+The `LF` after the command is optional (it used to be required).
+
+`progress`
+~~~~~~~~~~
+Causes fast-import to print the entire `progress` line unmodified to
+its standard output channel (file descriptor 1) when the command is
+processed from the input stream.  The command otherwise has no impact
+on the current import, or on any of fast-import's internal state.
+
+....
+	'progress' SP <any> LF
+	LF?
+....
+
+The `<any>` part of the command may contain any sequence of bytes
+that does not contain `LF`.  The `LF` after the command is optional.
+Callers may wish to process the output through a tool such as sed to
+remove the leading part of the line, for example:
+
+====
+	frontend | git-fast-import | sed 's/^progress //'
+====
+
+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.
 
 Tips and Tricks
 ---------------
@@ -840,6 +897,15 @@ This will take longer, but will also produce a smaller packfile.
 You only need to expend the effort once, and everyone using your
 project will benefit from the smaller repository.
 
+Include Some Progress Messages
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Every once in a while have your frontend emit a `progress` message
+to fast-import.  The contents of the messages are entirely free-form,
+so one suggestion would be to output the current month and year
+each time the current commit date moves into the next month.
+Your users will feel better knowing how much of the data stream
+has been processed.
+
 
 Packfile Optimization
 ---------------------