doc: document and test `@` prefix for raw timestamps
PATCH v2 1/1 doc: document and test `@` prefix for raw timestamps
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).
---
Fixed the asciidoc formatting, removed parens around YYYYMMDD example.
Documentation/date-formats.adoc | 5 +++++ t/t0006-date.sh | 11 +++++++++++ 2 files changed, 16 insertions(+)
Documentation/date-formats.adoc +5 -0
@@ -9,6 +9,11 @@ Git internal format:: `<unix-timestamp>` is the number of seconds since the UNIX epoch. `<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
t/t0006-date.sh +11 -0
@@ -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
Signature · 1 line
2.53.0
Quoted 10 lines · 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 asYYYYMMDD, 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 in2c733fb24c10a9d7aacc51f956bf9b7881980870(parse_date(): '@' prefix forces git-timestamp, 2012-02-02) but was never documented.
Quoted 7 lines
Document the
@prefix inDocumentation/date-formats.adocto make this behavior explicit. Also add test cases tot/t0006-date.shto verify and demonstrate the difference between prefixed and unprefixed small timestamps (e.g.,@2000vs2000).Signed-off-by Luna Schwalbe <[email protected]>Co-authored-by Junio C Hamano <[email protected]>
One nit: the order of trailers is wrong, as your Signed-off-by trailer should always be the last line of the commit message.
It would also be great to send the new version of a series as a reply to the previous version, so that it becomes easier for reviewers to connect the two series.
You can use a tool like b4, which can nowadays be configured exactly like this with git config set b4.send-same-thread shallow. b4 overall makes all of the mailing list wrangling a ton easier. Makes me wonder whether we should maybe highlight this tool more in our docs.
The patch itself looks good to me, thanks!
Patrick
Quoted 4 lines · Patrick Steinhardt
You can use a tool like b4, which can nowadays be configured exactly like this with
git config set b4.send-same-thread shallow. b4 overall makes all of the mailing list wrangling a ton easier. Makes me wonder whether we should maybe highlight this tool more in our docs.
It would be a very much welcome change.
And "b4" also helps the receiving end, not just the sender. With "b4" finding the latest round automatically, getting updated round once a topic is in my tree is a breeze, thanks to the amlog notes. Essentially, I detach the HEAD at the previous base commit (often a bit older 'master', but a few prerequisite topis merged into it), give "b4 am -o-" a message-id of one of the patches I have queued to download the latest and pipe that to "git am -s". That way, both "git range-diff @{-1}..." and "git diff @{-1}" become very effective ways to see what changes were made to the topic.
Quoted 15 lines · 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 asYYYYMMDD, 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 in2c733fb24c10a9d7aacc51f956bf9b7881980870(parse_date(): '@' prefix forces git-timestamp, 2012-02-02) but was never documented.Document the
@prefix inDocumentation/date-formats.adocto make this behavior explicit. Also add test cases tot/t0006-date.shto verify and demonstrate the difference between prefixed and unprefixed small timestamps (e.g.,@2000vs2000).
Quoted 4 lines
Signed-off-by Luna Schwalbe <[email protected]>Co-authored-by Junio C Hamano <[email protected]>---
Fixed the asciidoc formatting, removed parens around YYYYMMDD example.
Looks good.
Next time, when sending a [v2] patch of a singleton topic, please make it a reply e-mail message to the [v1] message. That would make it easier to see how patches evolved in mailing list archive. E.g., https://lore.kernel.org/git/$message_id would show both rounds (including the review comments they received) on the same page.
Will queue. Thanks.
Quoted 49 lines
Documentation/date-formats.adoc | 5 +++++ t/t0006-date.sh | 11 +++++++++++ 2 files changed, 16 insertions(+)Documentation/date-formats.adoc +5
-0@@ -9,6 +9,11 @@ Git internal format:: `<unix-timestamp>` is the number of seconds since the UNIX epoch. `<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 examplet/t0006-date.sh +11
-0@@ -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
Thanks to both of you for pointing out my mistakes! I'll make sure to do it right next time.