@matheusbsbs / matheus-bagliano / commits / 4018dc29ee

doc: document and test `@` prefix for raw timestamps

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 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 <dev@luna.gl> Co-authored-by: Junio C Hamano <gitster@pobox.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>

Luna Schwalbe committed Jun 2, 2026 at 10:17 UTC 4018dc29eea31e4273c0f1b02effe6ee852f3898

2 files changed +16

Documentation/date-formats.adoc

@@ -9,6 +9,11 @@ Git internal format::

9 `<unix-timestamp>` is the number of seconds since the UNIX epoch.

10 `<time-zone-offset>` is a positive or negative offset from UTC.

11 For example CET (which is 1 hour ahead of UTC) is `+0100`.

12 ++

13 +It is safer to prepend the `<unix-timestamp>` with `@` (e.g.,

14 +`@0 +0000`), which forces Git to interpret it as a raw timestamp. This

15 +is required for values less than 100,000,000 (which have fewer than 9

16 +digits) to avoid confusion with other date formats like `YYYYMMDD`.

18 RFC 2822::

19 The standard date format as described by RFC 2822, for example

t/t0006-date.sh

+11

@@ -138,6 +138,13 @@ check_parse '1969-12-31 23:59:59 Z' bad

138 check_parse '1969-12-31 23:59:59 +11' bad

139 check_parse '1969-12-31 23:59:59 -11' bad

140

141 +# pathologically small timestamps requiring `@` prefix

142 +check_parse '@0 +0000' '1970-01-01 00:00:00 +0000'

143 +check_parse '@99999999 +0000' '1973-03-03 09:46:39 +0000'

144 +check_parse '99999999 +0000' bad

145 +check_parse '@100000000 +0000' '1973-03-03 09:46:40 +0000'

146 +check_parse '100000000 +0000' '1973-03-03 09:46:40 +0000'

147 +

148 REQUIRE_64BIT_TIME=HAVE_64BIT_TIME

149 check_parse '2099-12-31 23:59:59' '2099-12-31 23:59:59 +0000'

150 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'

202 check_approxidate '2008-12-01' '2008-12-01 19:20:00'

203 check_approxidate '2009-12-01' '2009-12-01 19:20:00'

204

205 +# ambiguous raw timestamp

206 +check_approxidate '2000 +0000' '2000-08-30 19:20:00'

207 +check_approxidate '@2000 +0000' '1970-01-01 00:33:20'

208 +

209 check_date_format_human() {

210 t=$(($GIT_TEST_DATE_NOW - $1))

211 echo "$t -> $2" >expect