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

From: Jeff King <peff@peff.net>
Date: Jul 27, 2016, 20:16 UTC
Message-ID: <20160727201651.GA26984@sigill.intra.peff.net>
In-Reply-To: <xmqqtwfavo21.fsf@gitster.mtv.corp.google.com>

On Wed, Jul 27, 2016 at 01:11:34PM -0700, Junio C Hamano wrote:

Show 9 quoted lines

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

Good explanation.

Show 12 quoted lines

> 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")`).

I do find this by itself a little hard to parse. Maybe:

  `--date=raw` shows the date as seconds since the epoch (1970-01-01
  00:00:00 UTC), followed by a space, and then the timezone as an offset
  from UTC (a `+` or `-` with four digits; the first two are hours, and
  the second two are minutes). I.e., as if the timestamp were formatted
  with `strftime("%s %z")`).

-Peff