It was suggested on the mailing list that being able to use `from`
in any commit to reset the current branch is useful in some types of
importers, such as a darcs importer.

We originally did not permit resetting an existing branch with a
new `from` command during a `commit` command, but this restriction
was only to help debug the hacked up cvs2svn that Jon Smirl was
developing in parallel with git-fast-import.  It is probably more
of a problem to disallow it than to allow it.  So now we permit a
`from` during any `commit`.

While making the changes required to permit multiple `from`
commands on the same branch, I discovered we no longer needed the
last_commit field to be set to 0 during a reset, so that was removed.
(Reset was originally setting the field to 0 to signal cmd_from()
that it was OK to execute on the branch.)

While poking around in this section of fast-import I also realized
the `reset` command was not working as intended if the corresponding
`from` command was omitted (as allowed by the BNF grammar and the
code).  If `from` was omitted we cleared out the tree but we left
the tree SHA-1 and parent commit SHA-1 intact.  This is not what
the user intended in this case.  Instead they would be trying to
reset the branch to have no parent and to have no tree, making the
branch look new-born during the next commit.  We now clear these
SHA-1 values during `reset`, ensuring the branch looks new-born if
`from` does not get supplied.

New test cases for these were also added.
Signed-off-by: NShawn O. Pearce <spearce@spearce.org>

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

Most users don't need the pack boundary information that fast-import
was printing to standard output, especially if they were calling
it with --quiet.

Those users who do want this information probably want it captured
so they can go back and use it to repack the imported repository.
So dumping the boundary commits to a log file makes more sense then
printing them to standard output.
Signed-off-by: NShawn O. Pearce <spearce@spearce.org>

Its spelled 'fast-import', not 'gfi'.  Linus and Dscho have both
recently pointed this out to me on the mailing list.
Signed-off-by: NShawn O. Pearce <spearce@spearce.org>

Minor documentation improvements, as suggested on the Git mailing
list by Horst H. von Brand and Karl Hasselström.
Signed-off-by: NShawn O. Pearce <spearce@spearce.org>

I wrote this documentation with asciidoc 7.1.2, but apparently
asciidoc 8 assumes ^ means superscript.  The solution was already
documented in rev-parse's manpage and is to use {caret} instead.
Signed-off-by: NShawn O. Pearce <spearce@spearce.org>

There has been some informative lessons learned in the gfi user
community, and these really should be written down and documented
for future generations of frontend developers.
Signed-off-by: NShawn O. Pearce <spearce@spearce.org>

If the frontend asks us to checkpoint (via the explicit checkpoint
command) its probably because they are afraid the current import
will crash/fail/whatever and want to make sure they can pickup from
the last checkpoint.  To do that sort of recovery, we will need the
current tip of every branch and tag available at the next startup.
Signed-off-by: NShawn O. Pearce <spearce@spearce.org>

Often users will be running fast-import from within a larger frontend
process, and this may be a frequent periodic tool such as a future
edition of `git-svn fetch`.  We don't want to bombard users with our
large stats output if they won't be interested in it, so `--quiet`
is now an option to make gfi be more silent.
Signed-off-by: NShawn O. Pearce <spearce@spearce.org>

Some frontends may not be able to (easily) keep track of which files
are included in the branch, and which aren't.  Performing this
tracking can be tedious and error prone for the frontend to do,
especially if its foreign data source cannot supply the changed
path list on a per-commit basis.

fast-import now allows a frontend to request that a branch's tree
be wiped clean (reset to the empty tree) at the start of a commit,
allowing the frontend to feed in all paths which belong on the branch.

This is ideal for a tar-file importer frontend, for example, as
the frontend just needs to reformat the tar data stream into a gfi
data stream, which may be something a few Perl regexps can take
care of. :)
Signed-off-by: NShawn O. Pearce <spearce@spearce.org>

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>