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 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
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.
Thanks to both of you for pointing out my mistakes! I'll make sure to do it right next time.