{"thread":{"id":"65728","subject":"[PATCH] doc: document and test `@` prefix for raw timestamps","startedAt":"2026-06-01T21:40:35Z","lastAt":"2026-06-02T09:10:37Z","messageCount":5,"participants":["Luna Schwalbe","Junio C Hamano","Jeff King"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"544425","messageId":"20260601213944.645731-2-dev@luna.gl","threadId":"65728","inReplyTo":null,"subject":"[PATCH] doc: document and test `@` prefix for raw timestamps","fromName":"Luna Schwalbe","fromEmail":"dev@luna.gl","sentAt":"2026-06-01T21:39:45Z","receivedAt":"2026-06-01T21:40:35Z","isPatch":true,"body":"The Git internal date format ` `\nfails to parse when the timestamp is less than 100,000,000 (fewer than\n9 digits). This happens to avoid potential ambiguity with other date\nformats such as `YYYYMMDD`, especially when used with approxidate.\n\nTo force the parser to interpret the value as a raw timestamp, it must\nbe prefixed with `@` (e.g., `@0 +0000`). This behavior was introduced\nin 2c733fb24c10a9d7aacc51f956bf9b7881980870 (parse_date(): '@' prefix\nforces git-timestamp, 2012-02-02) but was never documented.\n\nDocument the `@` prefix in `Documentation/date-formats.adoc` to make\nthis behavior explicit. Also add test cases to `t/t0006-date.sh` to\nverify and demonstrate the difference between prefixed and unprefixed\nsmall timestamps (e.g., `@2000` vs `2000`).\n\nSigned-off-by: Luna Schwalbe \nCo-authored-by: Junio C Hamano \n---\nI switched out the YYYYMMDD tests as that format doesn't appear to be\nunderstood by either parse or approxidate.\n\n Documentation/date-formats.adoc | 6 ++++++\n t/t0006-date.sh | 11 +++++++++++\n 2 files changed, 17 insertions(+)\n\ndiff --git a/Documentation/date-formats.adoc b/Documentation/date-formats.adoc\nindex e24517c49..83f676585 100644\n--- a/Documentation/date-formats.adoc\n+++ b/Documentation/date-formats.adoc\n@@ -10,6 +10,12 @@ Git internal format::\n \t`` is a positive or negative offset from UTC.\n \tFor example CET (which is 1 hour ahead of UTC) is `+0100`.\n \n+ It is safer to prepend the `` with `@`\n+ (e.g., `@0 +0000`), which forces Git to interpret it as a raw\n+ timestamp. This is required for values less than 100,000,000\n+ (which have fewer than 9 digits) to avoid confusion with other\n+ date formats (like `YYYYMMDD`).\n+\n RFC 2822::\n \tThe standard date format as described by RFC 2822, for example\n \t`Thu, 07 Apr 2005 22:13:13 +0200`.\ndiff --git a/t/t0006-date.sh b/t/t0006-date.sh\nindex 53ced36df..8b4e1870b 100755\n--- a/t/t0006-date.sh\n+++ b/t/t0006-date.sh\n@@ -138,6 +138,13 @@ check_parse '1969-12-31 23:59:59 Z' bad\n check_parse '1969-12-31 23:59:59 +11' bad\n check_parse '1969-12-31 23:59:59 -11' bad\n \n+# pathologically small timestamps requiring `@` prefix\n+check_parse '@0 +0000' '1970-01-01 00:00:00 +0000'\n+check_parse '@99999999 +0000' '1973-03-03 09:46:39 +0000'\n+check_parse '99999999 +0000' bad\n+check_parse '@100000000 +0000' '1973-03-03 09:46:40 +0000'\n+check_parse '100000000 +0000' '1973-03-03 09:46:40 +0000'\n+\n REQUIRE_64BIT_TIME=HAVE_64BIT_TIME\n check_parse '2099-12-31 23:59:59' '2099-12-31 23:59:59 +0000'\n check_parse '2099-12-31 23:59:59 +00' '2099-12-31 23:59:59 +0000'\n@@ -195,6 +202,10 @@ check_approxidate '6AM, June 7, 2009' '2009-06-07 06:00:00'\n check_approxidate '2008-12-01' '2008-12-01 19:20:00'\n check_approxidate '2009-12-01' '2009-12-01 19:20:00'\n \n+# ambiguous raw timestamp\n+check_approxidate '2000 +0000' '2000-08-30 19:20:00'\n+check_approxidate '@2000 +0000' '1970-01-01 00:33:20'\n+\n check_date_format_human() {\n \tt=$(($GIT_TEST_DATE_NOW - $1))\n \techo \"$t -> $2\" >expect\n-- \n2.53.0\n\n"},{"id":"544452","messageId":"xmqqfr35zt6h.fsf@gitster.g","threadId":"65728","inReplyTo":"20260601213944.645731-2-dev@luna.gl","subject":"Re: [PATCH] doc: document and test `@` prefix for raw timestamps","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2026-06-02T00:23:34Z","receivedAt":"2026-06-02T00:23:37Z","isPatch":true,"body":"Luna Schwalbe writes:\n\n> diff --git a/Documentation/date-formats.adoc b/Documentation/date-formats.adoc\n> index e24517c49..83f676585 100644\n> --- a/Documentation/date-formats.adoc\n> +++ b/Documentation/date-formats.adoc\n> @@ -10,6 +10,12 @@ Git internal format::\n> \t`` is a positive or negative offset from UTC.\n> \tFor example CET (which is 1 hour ahead of UTC) is `+0100`.\n> \n> + It is safer to prepend the `` with `@`\n> + (e.g., `@0 +0000`), which forces Git to interpret it as a raw\n> + timestamp. This is required for values less than 100,000,000\n> + (which have fewer than 9 digits) to avoid confusion with other\n> + date formats (like `YYYYMMDD`).\n\nDoes this \"additional paragraph\" format correctly, instead of\nrendered as a literal block (typically typeset in typewriter font,\nmonospace)? Don't you need to do something like what is done for\n\"ISO 8601::\" that appears later in the same file? I.e. lose the\nfour-space indent and replace the blank line before it with a single\n'+' list continuation operator?\n\n> +# pathologically small timestamps requiring `@` prefix\n> +check_parse '@0 +0000' '1970-01-01 00:00:00 +0000'\n> +check_parse '@99999999 +0000' '1973-03-03 09:46:39 +0000'\n> +check_parse '99999999 +0000' bad\n\nThis is totally outside the scope of this topic, but we might want\nto enhance the rule a bit to declare this is *not* ambigous. As\nthere is no 99th month or 99th day, this cannot be in the YYYYMMDD\ndate format.\n\n> +check_parse '@100000000 +0000' '1973-03-03 09:46:40 +0000'\n> +check_parse '100000000 +0000' '1973-03-03 09:46:40 +0000'\n\n"},{"id":"544456","messageId":"20260602061752.GA695568@coredump.intra.peff.net","threadId":"65728","inReplyTo":"xmqqfr35zt6h.fsf@gitster.g","subject":"Re: [PATCH] doc: document and test `@` prefix for raw timestamps","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2026-06-02T06:17:52Z","receivedAt":"2026-06-02T06:17:54Z","isPatch":true,"body":"On Tue, Jun 02, 2026 at 09:23:34AM +0900, Junio C Hamano wrote:\n\n> > + It is safer to prepend the `` with `@`\n> > + (e.g., `@0 +0000`), which forces Git to interpret it as a raw\n> > + timestamp. This is required for values less than 100,000,000\n> > + (which have fewer than 9 digits) to avoid confusion with other\n> > + date formats (like `YYYYMMDD`).\n> \n> Does this \"additional paragraph\" format correctly, instead of\n> rendered as a literal block (typically typeset in typewriter font,\n> monospace)? Don't you need to do something like what is done for\n> \"ISO 8601::\" that appears later in the same file? I.e. lose the\n> four-space indent and replace the blank line before it with a single\n> '+' list continuation operator?\n\nYes, I think so. As a tip for contributors, running:\n\n cd Documentation\n ./doc-diff HEAD^ HEAD\n\nis often good for seeing a rough approximation of the rendered doc. It\nshows here that the result is incorrectly indented versus the rest of\nthe section.\n\nSadly it is somewhat limited in terms of typography, since it is diffing\nthe roff-rendered manpages. So you wouldn't realize that it is rendered\nin a typewriter font, as you would if you looked at the html output.\nSpot-checking the html is also a good thing to do when writing doc\npatches.\n\n-Peff\n"},{"id":"544468","messageId":"2194e42a-5c41-44e1-ba36-1599cbd41415@luna.gl","threadId":"65728","inReplyTo":"xmqqfr35zt6h.fsf@gitster.g","subject":"Re: [PATCH] doc: document and test `@` prefix for raw timestamps","fromName":"Luna Schwalbe","fromEmail":"dev@luna.gl","sentAt":"2026-06-02T08:15:15Z","receivedAt":"2026-06-02T08:15:17Z","isPatch":true,"body":" > Does this \"additional paragraph\" format correctly, instead of\n > rendered as a literal block (typically typeset in typewriter font,\n > monospace)? Don't you need to do something like what is done for\n > \"ISO 8601::\" that appears later in the same file? I.e. lose the\n > four-space indent and replace the blank line before it with a single\n > '+' list continuation operator?\n\nTerribly sorry, you're right of course, I somehow forgot to actually \nbuild and check the docs. Will send an updated patch right away.\n\n > This is totally outside the scope of this topic, but we might want\n > to enhance the rule a bit to declare this is *not* ambigous. As\n > there is no 99th month or 99th day, this cannot be in the YYYYMMDD\n > date format.\n\nI agree there is room for change with this rule, although I'm not sure \nhow sensible it is to start allowing certain values based on whether \nthey are also a valid calendar date or not (we'd end up trying to parse \nYYYYMMDD first, and only afterwards do the actual timestamp parsing; I \nfeel like this might just make the system less predictable for users in \npractice).\n\nAs far as I can tell the rule is technically not necessary at all (apart \nfrom some unusual approxidate interpretations like the `2000 +0000` \nexample, which I honestly think are more confusing than useful), seeing \nthat YYYYMMDD isn't a supported format anywhere.\n\nIf we want to have it as a safeguard tho, better documentation is \nprobably the most important aspect. As a user, ideally I'd love to get a \n\"ambiguous date format, prefix with @ if you intend to specify a raw \ntimestamp\" kind of error message, but I suspect that might be difficult \nto implement.\n"},{"id":"544481","messageId":"xmqqqzmpxq7o.fsf@gitster.g","threadId":"65728","inReplyTo":"2194e42a-5c41-44e1-ba36-1599cbd41415@luna.gl","subject":"Re: [PATCH] doc: document and test `@` prefix for raw timestamps","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2026-06-02T09:10:35Z","receivedAt":"2026-06-02T09:10:37Z","isPatch":true,"body":"Luna Schwalbe writes:\n\n> > Does this \"additional paragraph\" format correctly, instead of\n> > rendered as a literal block (typically typeset in typewriter font,\n> > monospace)? Don't you need to do something like what is done for\n> > \"ISO 8601::\" that appears later in the same file? I.e. lose the\n> > four-space indent and replace the blank line before it with a single\n> > '+' list continuation operator?\n>\n> Terribly sorry, you're right of course, I somehow forgot to actually \n> build and check the docs. Will send an updated patch right away.\n\nNo need to be sorry---we all make mistakes.\n\n> As far as I can tell the rule is technically not necessary at all (apart \n> from some unusual approxidate interpretations like the `2000 +0000` \n> example, which I honestly think are more confusing than useful), seeing \n> that YYYYMMDD isn't a supported format anywhere.\n\nSounds good. In any case, that is totally outside the scope of this\npatch.\n\nThanks.\n"}]}