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(+)

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?

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.

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

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

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

Luna Schwalbe <dev@luna.gl> writes:

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

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

Thanks.