As discussed on the mailing list, the documentation used here was
not quite accurate.  Improve upon it.
Signed-off-by: NShawn O. Pearce <spearce@spearce.org>

Signed-off-by: NShawn O. Pearce <spearce@spearce.org>

If fast-import is being used to update an existing branch of
a repository, the user may not want to lose commits if another
process updates the same ref at the same time.  For example, the
user might be using fast-import to make just one or two commits
against a live branch.

We now perform a fast-forward check during the ref updating process.
If updating a branch would cause commits in that branch to be lost,
we skip over it and display the new SHA1 to standard error.

This new default behavior can be overridden with `--force`, like
git-push and git-fetch.
Signed-off-by: NShawn O. Pearce <spearce@spearce.org>

Since some frontends may be working with source material where
the dates are only readily available as RFC 2822 strings, it is
more friendly if fast-import exposes Git's parse_date() function
to handle the conversion.  This way the frontend doesn't need
to perform the parsing itself.

The new --date-format option to fast-import can be used by a
frontend to select which format it will supply date strings in.
The default is the standard `raw` Git format, which fast-import
has always supported.  Format rfc2822 can be used to activate the
parse_date() function instead.

Because fast-import could also be useful for creating new, current
commits, the format `now` is also supported to generate the current
system timestamp.  The implementation of `now` is a trivial call
to datestamp(), but is actually a whole whopping 3 lines so that
fast-import can verify the frontend really meant `now`.

As part of this change I have added validation of the `raw` date
format.  Prior to this change fast-import would accept anything
in a `committer` command, even if it was seriously malformed.
Now fast-import requires the '> ' near the end of the string and
verifies the timestamp is formatted properly.
Signed-off-by: NShawn O. Pearce <spearce@spearce.org>

Corrected a couple of header markup lines which were shorter than the
actual header, and made the `data` commands two formats into a named
list, which matches how we document the two formats of the `M` command
within a commit.

Also tried to simplify the language about our decimal integer format;
Linus pointed out I was probably being too specific at the cost of
reduced readability.
Signed-off-by: NShawn O. Pearce <spearce@spearce.org>

Andy Parkins and Linus Torvalds both noticed that the description
of the timezone was incorrect.  Its not expressed in minutes.
Its more like "hhmm", where "hh" is the number of hours and "mm"
is the number of minutes shifted from GMT/UTC.
Signed-off-by: NShawn O. Pearce <spearce@spearce.org>

The --branch-log option and its associated code hasn't been used in
several months, as its not really very useful for debugging fast-import
or a frontend.  I don't plan on supporting it in this state long-term,
so I'm killing it now before it gets distributed to a wider audience.
Signed-off-by: NShawn O. Pearce <spearce@spearce.org>

This is a first pass at the manpage for git-fast-import.

I have tried to cover the input format in extreme detail, creating a
reference which is more detailed than the BNF grammar appearing in
the header of fast-import.c.  I have also covered some details about
gfi's performance and memory utilization, as well as the average
learning curve required to create a gfi frontend application (as it
is far lower than it might appear on first glance).

The documentation still lacks real example input streams, which may
turn out to be difficult to format in asciidoc due to the blank lines
which carry meaning within the format.
Signed-off-by: NShawn O. Pearce <spearce@spearce.org>