From: Junio C Hamano Date: Sat, 30 May 2026 07:43:01 GMT Subject: doc: document '@' prefix for raw timestamps Message-ID: In-Reply-To: Junio C Hamano writes: > This was introduced in 116eb3ab (parse_date(): allow ancient > git-timestamp, 2012-02-02) and 2c733fb2 (parse_date(): '@' prefix > forces git-timestamp, 2012-02-02) to allow specifying "ancient" > timestamps (like 0 +0000) without conflicting with YYYYMMDD date > formats. I do not think neither commit added documentation for this > '@' prefix, and Documentation/date-formats would be an excellent > place to do so. > > Care to whip up a patch? It might look something like this. ----- >8 ----- The Git internal date format ` ` fails to parse when the timestamp is less than 100,000,000 (fewer than 9 digits). This happens because the parser attempts to guess the format, and 8-digit numbers are interpreted as YYYYMMDD dates. To force the parser to interpret the value as a raw timestamp, it must be prefixed with `@` (e.g., `@0 +0000`). This behavior was introduced in 2c733fb24c (parse_date(): '@' prefix forces git-timestamp, 2012-02-02) but was never documented. Document the `@` prefix in `Documentation/date-formats.adoc` to make this behavior explicit. Also add test cases to `t/t0006-date.sh` to verify and demonstrate the difference between prefixed and unprefixed small timestamps (e.g., `@20000101` vs `20000101`). --- diff --git a/Documentation/date-formats.adoc b/Documentation/date-formats.adoc index e24517c496..93fd36449c 100644 --- a/Documentation/date-formats.adoc +++ b/Documentation/date-formats.adoc @@ -9,6 +9,13 @@ Git internal format:: `` is the number of seconds since the UNIX epoch. `` is a positive or negative offset from UTC. For example CET (which is 1 hour ahead of UTC) is `+0100`. ++ +It is safer to prepend the `` with `@` +(e.g., `@0 +0000`), which forces Git to interpret it as a raw +timestamp even if it looks like another format (like `YYYYMMDD`). +This is required for timestamps less than 100,000,000 (which have +fewer than 9 digits) to avoid confusion with other date formats. + RFC 2822:: The standard date format as described by RFC 2822, for example diff --git a/t/t0006-date.sh b/t/t0006-date.sh index 53ced36df4..e11c659716 100755 --- a/t/t0006-date.sh +++ b/t/t0006-date.sh @@ -138,6 +138,14 @@ check_parse '1969-12-31 23:59:59 Z' bad check_parse '1969-12-31 23:59:59 +11' bad check_parse '1969-12-31 23:59:59 -11' bad +# pathologically small or easily confused raw timestamps +check_parse '@99999999 +0000' '1973-03-03 09:46:39 +0000' +check_parse '@0 +0000' '1970-01-01 00:00:00 +0000' +check_parse '99999999 +0000' bad +check_parse '20000101 +0000' '2000-01-01 00:00:00 +0000' +check_parse '@20000101 +0000' '1970-08-20 11:35:01 +0000' + + REQUIRE_64BIT_TIME=HAVE_64BIT_TIME check_parse '2099-12-31 23:59:59' '2099-12-31 23:59:59 +0000' check_parse '2099-12-31 23:59:59 +00' '2099-12-31 23:59:59 +0000'