Volume XXII, number 280Wednesday, October 7, 2026Latest message 53 minutes ago

The Git List

News and archive of git@vger.kernel.org, since April 2005

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

5 messages between Jun 2, 2026 and Jun 2, 2026, from Luna Schwalbe, Patrick Steinhardt, Junio C Hamano.

Plain Markdown or JSON for tools and agents. Diffs are folded; open one to read it.

Luna SchwalbeJun 2, 2026, 08:17 UTC on lore

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>
---
Fixed the asciidoc formatting, removed parens around YYYYMMDD example.
 Documentation/date-formats.adoc |  5 +++++
 t/t0006-date.sh                 | 11 +++++++++++
 2 files changed, 16 insertions(+)
Show changes to 2 files +16 −0

Documentation/date-formats.adoc, t/t0006-date.sh

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::
 	`<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. 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

-- 
2.53.0
Patrick SteinhardtJun 2, 2026, 08:44 UTC in reply to Luna Schwalbe on lore

Re: [PATCH v2] doc: document and test `@` prefix for raw timestamps

On Tue, Jun 02, 2026 at 10:17:36AM +0200, Luna Schwalbe wrote:
Show 17 quoted lines
> 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>

One nit: the order of trailers is wrong, as your Signed-off-by trailer should always be the last line of the commit message.

It would also be great to send the new version of a series as a reply to the previous version, so that it becomes easier for reviewers to connect the two series.

You can use a tool like b4, which can nowadays be configured exactly like this with `git config set b4.send-same-thread shallow`. b4 overall makes all of the mailing list wrangling a ton easier. Makes me wonder whether we should maybe highlight this tool more in our docs.

The patch itself looks good to me, thanks!
Patrick
Junio C HamanoJun 2, 2026, 09:14 UTC in reply to Luna Schwalbe on lore

Re: [PATCH v2] doc: document and test `@` prefix for raw timestamps

Luna Schwalbe <dev@luna.gl> writes:
Show 19 quoted lines
> 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>
> ---
> 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.
Show 49 quoted lines
>  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::
>  	`<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. 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
Junio C HamanoJun 2, 2026, 09:20 UTC in reply to Patrick Steinhardt on lore

Re: [PATCH v2] doc: document and test `@` prefix for raw timestamps

Patrick Steinhardt <ps@pks.im> writes:
> You can use a tool like b4, which can nowadays be configured exactly
> like this with `git config set b4.send-same-thread shallow`. b4 overall
> makes all of the mailing list wrangling a ton easier. Makes me wonder
> whether we should maybe highlight this tool more in our docs.
It would be a very much welcome change.

And "b4" also helps the receiving end, not just the sender. With "b4" finding the latest round automatically, getting updated round once a topic is in my tree is a breeze, thanks to the amlog notes. Essentially, I detach the HEAD at the previous base commit (often a bit older 'master', but a few prerequisite topis merged into it), give "b4 am -o-" a message-id of one of the patches I have queued to download the latest and pipe that to "git am -s". That way, both "git range-diff @{-1}..." and "git diff @{-1}" become very effective ways to see what changes were made to the topic.

Luna SchwalbeJun 2, 2026, 16:35 UTC in reply to Junio C Hamano on lore

Re: [PATCH v2] doc: document and test `@` prefix for raw timestamps

Thanks to both of you for pointing out my mistakes! I'll make sure to do it right next time.

Back to recent threads