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

From: Junio C Hamano <gitster@pobox.com>
Date: Sep 3, 2008, 18:36 UTC
Message-ID: <7vtzcxaxgr.fsf@gitster.siamese.dyndns.org>
In-Reply-To: <1220431352-30605-1-git-send-email-bert.wesarg@googlemail.com>

Bert Wesarg <bert.wesarg@googlemail.com> writes:

Show 8 quoted lines

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