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

Junio C Hamano [off-list ref] writes:

Sergey Organov [off-list ref] writes:

quoted

quoted

quoted

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

That's were our disagreement actually is, and that's what I've tried to
fix with s/name/reference/, and that's why I'm against s/name/object
name/.

Rather than being more (and more) specific at every opportunity, one
needs a good reason to get more specific. In this particular case,
general DAG terminology seems to be enough to describe git-merge
semantics, thus using GIT specifics is unfounded.

It may be debatable if we want to give the description of what is
exactly recorded at that point of the document,

Exactly. My point in this particular discussion is that details of
recording of references to parents don't belong here, even though to
tell the truth I think they don't belong to git _user_ documentation at
all.

but I personally
think that the users deserve a chance to learn how a merge is
recorded in "git merge" documentation.

I doubt a user will gain anything from this sacred knowledge suddenly
being thrown on him when what she is looking for is understanding of
basic merge semantics in GIT.

That said, if you still disagree, please feel free to just drop the
patch.

-- Sergey