Re: git-fast-import

["Shawn O. Pearce" <spearce@spearce.org>]

Linus Torvalds <torvalds@linux-foundation.org> wrote:
> Btw, one thing that might be a good idea to document very clearly:
> 
>  - in the native git format, the offset from UTC has *nothing* to do with 
>    the actual time itself. The time in native git is always in UTC, and 
>    the offset from UTC does not change "time" - it's purely there to tell 
>    in which timezone the event happened.
> 
>    So 12345678 +0000 and 12345678 -0700 are *exactly*the*same*date*, 
>    except event one happened in UTC, and the other happened in UTC-7.
> 
>  - in rfc2822 format, the offset from UTC actually *changes* the date. The 
>    date "Oct 12, 2006 20:00:00" will be two _different_ times when you say 
>    it is in PST or in UTC.

Here is the current language relating to date parsing in gfi:

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 <offutc>`.
	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 local offset is specified by `<offutc>` as a positive or negative
offset from UTC.  For example EST (which is 5 hours behind UTC)
would be expressed in `<tz>` by ``-0500'' while UTC is ``+0000''.
The local offset does not affect `<time>`; it is used only as an
advisement to help formatting routines display the timestamp.
+
If the local offset is not available in the source material, use
``+0000'', or the most common local offset.  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 offset from UTC 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.
+
Unlike the `raw` format above, the timezone/UTC offset information
contained in an RFC 2822 date string is used to adjust the date
value to UTC prior to storage.  Therefore it is important that
this information be as accurate as possible.
+
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`.