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

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

Sergey Organov <sorganov@gmail.com> writes:

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