Re: [PATCH v2 3/5] Add 'human' date format documentation

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

"Stephen P. Smith" <ischis2@cox.net> writes:

> diff --git a/Documentation/git-log.txt b/Documentation/git-log.txt
> index 90761f1694..1d2d932c76 100644
> --- a/Documentation/git-log.txt
> +++ b/Documentation/git-log.txt
> @@ -193,6 +193,10 @@ log.date::
>  	`--date` option.)  Defaults to "default", which means to write
>  	dates like `Sat May 8 19:35:34 2010 -0500`.
>  
> +	If the format is set to "auto:foo", then if the pager is in
> +	use format "foo" will be the used for the date format, otherwise
> +	"default" will be used.
> +

This text is good, but this would break ASCIIdoc formatting,
wouldn't it?  Observe how "notes.displayRef::" section does
three-paragraph description and mimick it to make this two-paragraph
description, perhaps.

>  log.follow::
>  	If `true`, `git log` will act as if the `--follow` option was used when
>  	a single <path> is given.  This has the same limitations as `--follow`,
> diff --git a/Documentation/rev-list-options.txt b/Documentation/rev-list-options.txt
> index bab5f50b17..5d58f35d19 100644
> --- a/Documentation/rev-list-options.txt
> +++ b/Documentation/rev-list-options.txt
> @@ -835,6 +835,12 @@ 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.
>  +
> +`--date=human` shows the timezone if it matches the current time-zone,

Is it clear in the context that "it" refers to "the timestamp being
shown"?

I think the behaviour is that timezone is shown only the timestamp
being shown is from a different timezone (i.e. if it *does* *not*
match), though.

> +and doesn't print the whole date if that matches (ie skip printing
> +year for dates that are "this year", but also skip the whole date
> +itself if it's in the last few days and we can just say what weekday
> +it was).
> ++

... and also omit hour/minute part for a timestamp that is old
enough.

>  `--date=unix` shows the date as a Unix epoch timestamp (seconds since
>  1970).  As with `--raw`, this is always in UTC and therefore `-local`
>  has no effect.