OPTIONS
-------
+--date-format=<fmt>::
+ Specify the type of dates the frontend will supply to
+ gfi within `author`, `committer` and `tagger` commands.
+ See ``Date Formats'' below for details about which formats
+ are supported, and their syntax.
+
+--force::
+ Force updating modified existing branches, even if doing
+ so would cause commits to be lost (as the new commit does
+ not contain the old commit).
+
--max-pack-size=<n>::
Maximum size of each output packfile, expressed in MiB.
The default is 4096 (4 GiB) as that is the maximum allowed
Frontends can use this file to validate imports after they
have been completed.
-
Performance
-----------
The design of gfi allows it to import large projects in a minimum
or any other Git operation (including `git prune`, as loose objects
are never used by gfi).
-However, gfi does not lock the branch or tag refs it is actively
-importing. After EOF, during its ref update phase, gfi blindly
-overwrites each imported branch or tag ref. Consequently it is not
-safe to modify refs that are currently being used by a running gfi
-instance, as work could be lost when gfi overwrites the refs.
+gfi does not lock the branch or tag refs it is actively importing.
+After the import, during its ref update phase, gfi tests each
+existing branch ref to verify the update will be a fast-forward
+update (the commit stored in the ref is contained in the new
+history of the commit to be written). If the update is not a
+fast-forward update, gfi will skip updating that ref and instead
+prints a warning message. gfi will always attempt to update all
+branch refs, and does not stop on the first failure.
+
+Branch updates can be forced with `--force`, but its recommended that
+this only be used on an otherwise quiet repository. Using `--force`
+is not necessary for an initial import into an empty repository.
Technical Discussion
spaces in their name, or early termination of gfi when it encounters
unexpected input.
+Date Formats
+~~~~~~~~~~~~
+The following date formats are supported. A frontend should select
+the format it will use for this import by passing the format name
+in the `--date-format=<fmt>` command line option.
+
+`raw`::
+ This is the Git native format and is `<time> SP <tz>`.
+ It is also gfi's default format, if `--date-format` was
+ not specified.
++
+The time of the event is specified by `<time>` as the number of
+seconds since the UNIX epoch (midnight, Jan 1, 1970, UTC) and is
+written as an ASCII decimal integer.
++
+The timezone is specified by `<tz>` as a positive or negative offset
+from UTC. For example EST (which is typically 5 hours behind GMT)
+would be expressed in `<tz>` by ``-0500'' while GMT is ``+0000''.
++
+If the timezone is not available in the source material, use
+``+0000'', or the most common local timezone. For example many
+organizations have a CVS repository which has only ever been accessed
+by users who are located in the same location and timezone. In this
+case the user's timezone can be easily assumed.
++
+Unlike the `rfc2822` format, this format is very strict. Any
+variation in formatting will cause gfi to reject the value.
+
+`rfc2822`::
+ This is the standard email format as described by RFC 2822.
++
+An example value is ``Tue Feb 6 11:22:18 2007 -0500''. The Git
+parser is accurate, but a little on the lenient side. Its the
+same parser used by gitlink:git-am[1] when applying patches
+received from email.
++
+Some malformed strings may be accepted as valid dates. In some of
+these cases Git will still be able to obtain the correct date from
+the malformed string. There are also some types of malformed
+strings which Git will parse wrong, and yet consider valid.
+Seriously malformed strings will be rejected.
++
+If the source material is formatted in RFC 2822 style dates,
+the frontend should let gfi handle the parsing and conversion
+(rather than attempting to do it itself) as the Git parser has
+been well tested in the wild.
++
+Frontends should prefer the `raw` format if the source material
+is already in UNIX-epoch format, or is easily convertible to
+that format, as there is no ambiguity in parsing.
+
+`now`::
+ Always use the current time and timezone. The literal
+ `now` must always be supplied for `<when>`.
++
+This is a toy format. The current time and timezone of this system
+is always copied into the identity string at the time it is being
+created by gfi. There is no way to specify a different time or
+timezone.
++
+This particular format is supplied as its short to implement and
+may be useful to a process that wants to create a new commit
+right now, without needing to use a working directory or
+gitlink:git-update-index[1].
++
+If separate `author` and `committer` commands are used in a `commit`
+the timestamps may not match, as the system clock will be polled
+twice (once for each command). The only way to ensure that both
+author and committer identity information has the same timestamp
+is to omit `author` (thus copying from `committer`) or to use a
+date format other than `now`.
+
Commands
~~~~~~~~
gfi accepts several commands to update the current repository
....
'commit' SP <ref> LF
mark?
- ('author' SP <name> SP LT <email> GT SP <time> SP <tz> LF)?
- 'committer' SP <name> SP LT <email> GT SP <time> SP <tz> LF
+ ('author' SP <name> SP LT <email> GT SP <when> LF)?
+ 'committer' SP <name> SP LT <email> GT SP <when> LF
data
('from' SP <committish> LF)?
('merge' SP <committish> LF)?
`<name>` is free-form and may contain any sequence of bytes, except
`LT` and `LF`. It is typically UTF-8 encoded.
-The time of the change is specified by `<time>` as the number of
-seconds since the UNIX epoc (midnight, Jan 1, 1970, UTC) and is
-written in base-10 notation using US-ASCII digits. The committer's
-timezone is specified by `<tz>` as a positive or negative offset
-from UTC, in minutes. For example EST would be expressed in `<tz>`
-by ``-0500''.
+The time of the change is specified by `<when>` using the date format
+that was selected by the `--date-format=<fmt>` command line option.
+See ``Date Formats'' above for the set of supported formats, and
+their syntax.
`from`
^^^^^^
also accepted by `from` (see above).
`filemodify`
-^^^^^^^^^^
+^^^^^^^^^^^^
Included in a `commit` command to add a new file or change the
content of an existing file. This command has two different means
of specifying the content of the file.
of files in most projects use this mode. If in doubt, this is
what you want.
* `100755` or `755`: A normal, but executable, file.
-* `140000`: A symlink, the content of the file will be the link target.
+* `120000`: A symlink, the content of the file will be the link target.
In both formats `<path>` is the complete path of the file to be added
(if not already existing) or modified (if already existing).
It is recommended that `<path>` always be encoded using UTF-8.
-
`filedelete`
-^^^^^^^^^^
+^^^^^^^^^^^^
Included in a `commit` command to remove a file from the branch.
If the file removal makes its directory empty, the directory will
be automatically removed too. This cascades up the tree until the
....
where `<idnum>` is the number assigned by the frontend to this mark.
-The value of `<idnum>` is expressed in base 10 notation using
-US-ASCII digits. The value 0 is reserved and cannot be used as
+The value of `<idnum>` is expressed as an ASCII decimal integer.
+The value 0 is reserved and cannot be used as
a mark. Only values greater than or equal to 1 may be used as marks.
New marks are created automatically. Existing marks can be moved
....
'tag' SP <name> LF
'from' SP <committish> LF
- 'tagger' SP <name> SP LT <email> GT SP <time> SP <tz> LF
+ 'tagger' SP <name> SP LT <email> GT SP <when> LF
data
LF
....
exact byte count format, as it is more robust and performs better.
The delimited format is intended primarily for testing gfi.
-Exact byte count format:
-
+Exact byte count format::
+ The frontend must specify the number of bytes of data.
++
....
'data' SP <count> LF
<raw> LF
....
-
++
where `<count>` is the exact number of bytes appearing within
-`<raw>`. The value of `<count>` is expressed in base 10 notation
-using US-ASCII digits. The `LF` on either side of `<raw>` is not
+`<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.
-Delimited format:
-
+Delimited format::
+ A delimiter string is used to mark the end of the data.
+ gfi will compute the length by searching for the delimiter.
+ This format is primarly useful for testing and is not
+ recommended for real data.
++
....
'data' SP '<<' <delim> LF
<raw> LF
<delim> LF
....
-
++
where `<delim>` is the chosen delimiter string. The string `<delim>`
must not appear on a line by itself within `<raw>`, as otherwise
gfi will think the data ends earlier than it really does. The `LF`