Re: [PATCH 5/6] Documentation/git-merge.txt: improve short description in DESCRIPTION

From: Junio C Hamano <gitster@pobox.com>
Date: Oct 6, 2016, 17:46 UTC
Message-ID: <xmqqshs9l69h.fsf@gitster.mtv.corp.google.com>
In-Reply-To: <87mvihpsla.fsf@javad.com>

Sergey Organov <sorganov@gmail.com> writes:

Show 16 quoted lines

>>> Last, if "reference" is not good enough and we get to internals anyway,
>>> why not say SHA1 then?
>>
>> Because that is still colloquial? I think s/name/object name/ is a
>> sensible change, but not s/name/reference/.
>
> No, "reference" is more sensible here than any of "name", "object name",
> or "SHA-1", the same way as here:
>
> $ git help glossary
> [...]
> chain
>         A list of objects, where each object in the list contains a
>         reference to its successor (for example, the successor of a
>         commit could be one of its parents).
> [...]

The entry for "chain" and the description under discussion have stress on different aspect, though. The description of "chain" is more general: an object refers to another object by referring to it, by unspecified means. The reason why it is left unspecified is because the way a tree object refers to blobs and trees is different from the way a commit object refers to its parents (the former has object names of blobs and trees in the tree entries; the latter uses "parent" entries in the object header part to record object names of parent commits). It wants to stress more on the fact that there is some mechanism to associate one object to others, than how that association/linkage is expressed.

The way the resulting commit is described in the original text of "git merge" description stresses more on "how" by being a lot more specific to commit objects. It does not just say "refers to parents (by unspecified means)"; instead it tries to say what exactly are recorded, i.e. the parents are referred to by recording the object names of them in a new commit object. It stresses more on "how" (because it can afford to be more specific, unlike the description of more general concept of a "chain").

It may be debatable if we want to give the description of what is exactly recorded at that point of the document, but I personally think that the users deserve a chance to learn how a merge is recorded in "git merge" documentation.