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

[Junio C Hamano <gitster@pobox.com>]

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'