Re: [PATCH] doc: document and test `@` prefix for raw timestamps
- From
Junio C Hamano <gitster@pobox.com>
- Date
- Jun 2, 2026, 00:23 UTC
- Message-ID
- <xmqqfr35zt6h.fsf@gitster.g>
- In-Reply-To
- <20260601213944.645731-2-dev@luna.gl>
Luna Schwalbe <dev@luna.gl> writes:
Show 13 quoted lines
> 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'