From: Junio C Hamano Date: Tue, 02 Jun 2026 09:14:08 GMT Subject: Re: [PATCH v2] doc: document and test `@` prefix for raw timestamps Message-ID: In-Reply-To: <20260602081924.673763-2-dev@luna.gl> Luna Schwalbe writes: > The Git internal date format ` ` > fails to parse when the timestamp is less than 100,000,000 (fewer than > 9 digits). This happens to avoid potential ambiguity with other date > formats such as `YYYYMMDD`, especially when used with approxidate. > > 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 2c733fb24c10a9d7aacc51f956bf9b7881980870 (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., `@2000` vs `2000`). > > Signed-off-by: Luna Schwalbe > Co-authored-by: Junio C Hamano > --- > Fixed the asciidoc formatting, removed parens around YYYYMMDD example. Looks good. Next time, when sending a [v2] patch of a singleton topic, please make it a reply e-mail message to the [v1] message. That would make it easier to see how patches evolved in mailing list archive. E.g., https://lore.kernel.org/git/$message_id would show both rounds (including the review comments they received) on the same page. Will queue. Thanks. > Documentation/date-formats.adoc | 5 +++++ > t/t0006-date.sh | 11 +++++++++++ > 2 files changed, 16 insertions(+) > > diff --git a/Documentation/date-formats.adoc b/Documentation/date-formats.adoc > index e24517c49..330424b2b 100644 > --- a/Documentation/date-formats.adoc > +++ b/Documentation/date-formats.adoc > @@ -9,6 +9,11 @@ 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. This > +is required for values less than 100,000,000 (which have fewer than 9 > +digits) to avoid confusion with other date formats like `YYYYMMDD`. > > 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 53ced36df..8b4e1870b 100755 > --- a/t/t0006-date.sh > +++ b/t/t0006-date.sh > @@ -138,6 +138,13 @@ 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 timestamps requiring `@` prefix > +check_parse '@0 +0000' '1970-01-01 00:00:00 +0000' > +check_parse '@99999999 +0000' '1973-03-03 09:46:39 +0000' > +check_parse '99999999 +0000' bad > +check_parse '@100000000 +0000' '1973-03-03 09:46:40 +0000' > +check_parse '100000000 +0000' '1973-03-03 09:46:40 +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' > @@ -195,6 +202,10 @@ check_approxidate '6AM, June 7, 2009' '2009-06-07 06:00:00' > check_approxidate '2008-12-01' '2008-12-01 19:20:00' > check_approxidate '2009-12-01' '2009-12-01 19:20:00' > > +# ambiguous raw timestamp > +check_approxidate '2000 +0000' '2000-08-30 19:20:00' > +check_approxidate '@2000 +0000' '1970-01-01 00:33:20' > + > check_date_format_human() { > t=$(($GIT_TEST_DATE_NOW - $1)) > echo "$t -> $2" >expect