Re: [PATCH v2 2/6] date: make "local" orthogonal to date format

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

John Keeping <john@keeping.me.uk> writes:

> diff --git a/Documentation/rev-list-options.txt b/Documentation/rev-list-options.txt
> index a9b808f..5d28133 100644
> --- a/Documentation/rev-list-options.txt
> +++ b/Documentation/rev-list-options.txt
> @@ -702,12 +702,16 @@ include::pretty-options.txt[]
>  --date=(relative|local|default|iso|iso-strict|rfc|short|raw)::
>  	Only takes effect for dates shown in human-readable format, such
>  	as when using `--pretty`. `log.date` config variable sets a default
> -	value for the log command's `--date` option.
> +	value for the log command's `--date` option. By default, dates
> +	are shown in the original time zone (either committer's or
> +	author's). If `-local` is appended to the format (e.g.,
> +	`iso-local`), the user's local time zone is used instead.
>  +
>  `--date=relative` shows dates relative to the current time,
> -e.g. ``2 hours ago''.
> +e.g. ``2 hours ago''. The `-local` option cannot be used with
> +`--raw` or `--relative`.
>  +
> -`--date=local` shows timestamps in user's local time zone.
> +`--date=local` is an alias for `--date=default-local`.
>  +

This can also affect for-each-ref's "%(authordate:short)" and
friends.  We have this rather unfortunately detailed description:

    As a special case for the date-type fields, you may specify a format for
    the date by adding one of `:default`, `:relative`, `:short`, `:local`,
    `:iso8601`, `:rfc2822` or `:raw` to the end of the fieldname; e.g.
    `%(taggerdate:relative)`.

We would probably want to make this more vague by replacing "adding
one of..." with "adding ':' followed by date format name (see the
values the --date option to linkgit::git-rev-list[1] takes)" or
something like that.