Re: [PATCH v3 09/10] pretty: implement 'reference' format

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

Junio C Hamano <gitster@pobox.com> writes:

> Denton Liu <liu.denton@gmail.com> writes:
>
>> +* 'reference'
>> +
>> +	  <abbrev hash> (<title line>, <short author date>)
>
> s/title line/title/ as you definitely do *not* want a line with a
> title on it (and nothing else) in this context.
>
>> +This format is useful for referring to other commits when writing a new
>> +commit message. It uses the following canned user format:
>> +`%C(auto)%h (%s, %as)`. This means it will not respect options that
>> +change the output format such as `--date` `--no-abbrev-commit`, and
>> +`--walk-reflogs`.
>
> Ignoring of the '--date' may want to be eventually fixed, but for an
> initial cut, using %as in the canned format is a good approach for
> expediency.
> ...
> ...  I do not think I understand what you wanted to do by
> using `--walk-reflogs` with the format at all, either.

OK, I re-read the patch text and I understand what you wanted to
say.  The mention of --walk-reflogs in the new description is
grossly misleading.

   $ git log --pretty=ref --walk-reflogs @{now}

would work perfectly fine.  It is an instruction that tells "git
log" not to follow the commit ancestry from the commit that sits at
the current branch right now, but instead follow the history of what
commits used to sit at the tip of the current branch.

"--pretty=format:<anything>" overrides only the side effect of
"--walk-reflogs" that modifies traditional built-in formats.  But
the above makes it sound as if use of "--pretty=ref" somehow makes
our commands to ignore the entire effect of any option that has side
effect of changing the output format, which is not true.

The `--date` and `--decorate` options would be a good example of
options "that change the output format".  If you want to mention the
effect of this option on the `--walk-reflogs` option correctly, the
explanation must make sure that only the output aspect is affected.

Perhaps like this

	This format is used to refer another commit in a commit
	message as "<short hash> (<title>, <author date>)" and is
	the same as `--pretty=format:%C(auto)%h (%s, %as)`.  As with
	any `format:` with format placeholders, its output is not
	affected by other options like `--decorate` and
	`--walk-reflogs`.

I guess?

We would want to fix it in such a way that it uses %ad instead of
%as, but internally tweak the default date format to short unless
the --date option is given.

Thanks.