git/list[1] front-page[2] threads[3] people[4] search[5] about
 

doc: document '@' prefix for raw timestamps

From
Junio C Hamano <gitster@pobox.com>
Date
May 30, 2026, 07:43 UTC
Message-ID
<xmqqpl2de41m.fsf@gitster.g>
In-Reply-To
<xmqq7bolg762.fsf@gitster.g>
Junio C Hamano <gitster@pobox.com> writes:
Show 9 quoted lines
> 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 `<unix-timestamp> <time-zone-offset>` 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::
 	`<unix-timestamp>` is the number of seconds since the UNIX epoch.
 	`<time-zone-offset>` 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 `<unix-timestamp>` 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'
Previous: Junio C HamanoNext: Luna Schwalbe
Message 5 of 6 in “[BUG] internal date format does not accept small unix timestamps”
  1. Luna SchwalbeMay 29, 2026
  2. Kristoffer HaugsbakkMay 29, 2026
  3. Luna SchwalbeMay 29, 2026
  4. Junio C HamanoMay 29, 2026
  5. doc: document '@' prefix for raw timestampsJunio C Hamano, May 30, 2026
  6. Luna SchwalbeMay 31, 2026

Read the whole thread, see it on lore, or plain text.

$ cat FOOTERMessages come from the public archive at lore.kernel.org/git, fetched every hour. The front page is chosen and written each morning by an AI editor and can be wrong; the threads themselves are the record. About and API. For agents: an MCP server at https://gitlist.dev/mcp, and any thread, story or person page as Markdown by adding .md to its URL (or sending Accept: text/markdown). Details in /llms.txt.