Subject: Re: [PATCH v3] for-each-ref: `:short` format for `refname`

From: Junio C Hamano <[email-masked]>
Date: Wed, 03 Sep 2008 11:36:04 -0700

Bert Wesarg <[email-masked]> writes:

> Try to shorten the refname to a non-ambiguous name.
>
> Changes in v3:
>  * don't compare sha1's, its ambiguous if the short name
>    resovles to more than one ref
>  * use xstrdup()
>  * use indexes for the loops to clarify backward/forward
>    direction

Please don't do "Changes in v3" in the commit log message; do so after
"---" is very welcome as it gives people on the discussion _right now_
to understand the context of the change.

Also please do not omit discussion in the commit log message, to help
people _not_ on the discussion right now.

Your earlier versions will not appear on the history anywhere, and v3 is
the _only_ variant available to the people who need to understand what
this change was made for and why the code to implement the change was done
in the way the patch shows.  Write your commit log message to help people
who have "git show $this" and nothing else to figure these things out in
year 2010.

Namely:

 * Why "shortening" is a good thing?  For what use case this new feature
   was invented for?

 * What are the definitions of "shortening" and "non-ambiguous" in this
   feature's context?

In addition, for a complex feature with different possiblilities, it is a
good practice to describe what alternatatives and pros-and-cons among them
were considered while reaching this final version.  This is to help people
who would want to explore enhancement possibilities later; you beforehand
warn them about dead ends you have already explored.  For this particular
patch/feature, I do not think it is necessary, though.