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

From: Jeff King <peff@peff.net>
Date: Jul 27, 2016, 19:57 UTC
Message-ID: <20160727195703.GA8141@sigill.intra.peff.net>
In-Reply-To: <xmqq37mux3mz.fsf@gitster.mtv.corp.google.com>

On Wed, Jul 27, 2016 at 12:49:40PM -0700, Junio C Hamano wrote:

Show 12 quoted lines

> > @@ -746,7 +746,10 @@ 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 in the internal raw Git format `%s %z`
> > +format. 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.
> 
> Not your fault, but "internal raw Git format X format" sounds a bit
> clunky.

Yeah, I also noticed that while writing the original, but it just crossed over my line of "if I fix everything I don't like, this series will never get out the door". :)

Show 11 quoted lines

> 	shows the date in `%s %z` format (seconds since 1970-01-01
> 	00:00:00 UTC, space, timezone as sign and four digits)
>         
> or something like that?  I suspect %s is not a POSIX-kosher strftime
> conversion specifier, so from that point of view, perhaps making the
> text the authoritative description and demote the format string as a
> comment to help those who know strfmt, i.e.
> 
> 	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")`).

Yeah, I think referring to "%s %z" is pretty bad, as it's meaningless to people who don't know strftime() off the top of their head, and %s isn't even portable.

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.

-Peff