Re: [PATCH v3 5/6] date: document and test "raw-local" mode

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

Jeff King <peff@peff.net> writes:

> The second option you've shown here is much better, and I think this is
> worth fixing (and it should be in a new patch, and can go on top of the
> others).
>
> I'm not sure if it's worth calling out more clearly what the timezone
> means, since the epoch seconds are in UTC, as you noted here. The
> follow-on sentence explains what "-local" does, but not what it means in
> the non-local variant.

Hmm, that is another thing we can incrementally improve, I guess.

Here is 7/6 I've tentatively queued.  Note that I minimized the
reflowing of the paragraph you did in 5/6 so the patch may not apply
cleanly to your tree.

-- >8 --
Subject: [PATCH] date: clarify --date=raw description

"... in the internal raw Git format `%s %z` format." was clunky in
repeating "format" twice, and would not have helped those who do not
know that these are strftime(3) conversion specifiers.

Explain them with words, and demote the mention of `%s %z` to a
hint to help those who know them.

Signed-off-by: Junio C Hamano <gitster@pobox.com>
---
 Documentation/rev-list-options.txt | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/Documentation/rev-list-options.txt b/Documentation/rev-list-options.txt
index fd86ed1..d55e3ae 100644
--- a/Documentation/rev-list-options.txt
+++ b/Documentation/rev-list-options.txt
@@ -746,7 +746,9 @@ format, often found in email messages.
 +
 `--date=short` shows only the date, but not the time, in `YYYY-MM-DD` format.
 +
-`--date=raw` shows the date in the internal raw Git format `%s %z` format.
+`--date=raw` shows the date as seconds since 1970-01-01 00:00:00 UTC,
+space, timezone as sign and four digits (i.e. as if the timestamp were
+formatted with `strftime("%s %z")`).
 Note that the `-local` option does not affect the seconds-since-epoch
 value (which is always measured in UTC), but does switch the accompanying
 timezone value.
-- 
2.9.2-654-g4c312ab