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

From: Junio C Hamano <gitster@pobox.com>
Date: Nov 18, 2019, 01:42 UTC
Message-ID: <xmqqa78u3qot.fsf@gitster-ct.c.googlers.com>
In-Reply-To: <xmqqbltd7juo.fsf@gitster-ct.c.googlers.com>

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

Show 21 quoted lines

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