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

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

[Luna Schwalbe]

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>
---
I switched out the YYYYMMDD tests as that format doesn't appear to be
understood by either parse or approxidate.

 Documentation/date-formats.adoc |  6 ++++++
 t/t0006-date.sh                 | 11 +++++++++++
 2 files changed, 17 insertions(+)

diff --git a/Documentation/date-formats.adoc b/Documentation/date-formats.adoc
index e24517c49..83f676585 100644
--- a/Documentation/date-formats.adoc
+++ b/Documentation/date-formats.adoc
@@ -10,6 +10,12 @@ Git internal format::
 	`<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
 	`Thu, 07 Apr 2005 22:13:13 +0200`.
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

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

[Junio C Hamano]

Luna Schwalbe <dev@luna.gl> writes:

> diff --git a/Documentation/date-formats.adoc b/Documentation/date-formats.adoc
> index e24517c49..83f676585 100644
> --- a/Documentation/date-formats.adoc
> +++ b/Documentation/date-formats.adoc
> @@ -10,6 +10,12 @@ Git internal format::
>  	`<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`).

Does this "additional paragraph" format correctly, instead of
rendered as a literal block (typically typeset in typewriter font,
monospace)?  Don't you need to do something like what is done for
"ISO 8601::" that appears later in the same file?  I.e. lose the
four-space indent and replace the blank line before it with a single
'+' list continuation operator?

> +# 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

This is totally outside the scope of this topic, but we might want
to enhance the rule a bit to declare this is *not* ambigous.  As
there is no 99th month or 99th day, this cannot be in the YYYYMMDD
date format.

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

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

[Jeff King]

On Tue, Jun 02, 2026 at 09:23:34AM +0900, Junio C Hamano wrote:

> > +    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`).
> 
> Does this "additional paragraph" format correctly, instead of
> rendered as a literal block (typically typeset in typewriter font,
> monospace)?  Don't you need to do something like what is done for
> "ISO 8601::" that appears later in the same file?  I.e. lose the
> four-space indent and replace the blank line before it with a single
> '+' list continuation operator?

Yes, I think so. As a tip for contributors, running:

  cd Documentation
  ./doc-diff HEAD^ HEAD

is often good for seeing a rough approximation of the rendered doc. It
shows here that the result is incorrectly indented versus the rest of
the section.

Sadly it is somewhat limited in terms of typography, since it is diffing
the roff-rendered manpages. So you wouldn't realize that it is rendered
in a typewriter font, as you would if you looked at the html output.
Spot-checking the html is also a good thing to do when writing doc
patches.

-Peff

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

[Luna Schwalbe]

 > Does this "additional paragraph" format correctly, instead of
 > rendered as a literal block (typically typeset in typewriter font,
 > monospace)?  Don't you need to do something like what is done for
 > "ISO 8601::" that appears later in the same file?  I.e. lose the
 > four-space indent and replace the blank line before it with a single
 > '+' list continuation operator?

Terribly sorry, you're right of course, I somehow forgot to actually 
build and check the docs. Will send an updated patch right away.

 > This is totally outside the scope of this topic, but we might want
 > to enhance the rule a bit to declare this is *not* ambigous.  As
 > there is no 99th month or 99th day, this cannot be in the YYYYMMDD
 > date format.

I agree there is room for change with this rule, although I'm not sure 
how sensible it is to start allowing certain values based on whether 
they are also a valid calendar date or not (we'd end up trying to parse 
YYYYMMDD first, and only afterwards do the actual timestamp parsing; I 
feel like this might just make the system less predictable for users in 
practice).

As far as I can tell the rule is technically not necessary at all (apart 
from some unusual approxidate interpretations like the `2000 +0000` 
example, which I honestly think are more confusing than useful), seeing 
that YYYYMMDD isn't a supported format anywhere.

If we want to have it as a safeguard tho, better documentation is 
probably the most important aspect. As a user, ideally I'd love to get a 
"ambiguous date format, prefix with @ if you intend to specify a raw 
timestamp" kind of error message, but I suspect that might be difficult 
to implement.

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

[Junio C Hamano]

Luna Schwalbe <dev@luna.gl> writes:

>  > Does this "additional paragraph" format correctly, instead of
>  > rendered as a literal block (typically typeset in typewriter font,
>  > monospace)?  Don't you need to do something like what is done for
>  > "ISO 8601::" that appears later in the same file?  I.e. lose the
>  > four-space indent and replace the blank line before it with a single
>  > '+' list continuation operator?
>
> Terribly sorry, you're right of course, I somehow forgot to actually 
> build and check the docs. Will send an updated patch right away.

No need to be sorry---we all make mistakes.

> As far as I can tell the rule is technically not necessary at all (apart 
> from some unusual approxidate interpretations like the `2000 +0000` 
> example, which I honestly think are more confusing than useful), seeing 
> that YYYYMMDD isn't a supported format anywhere.

Sounds good.  In any case, that is totally outside the scope of this
patch.

Thanks.