Re: [PATCH v6] doc: add an explanation of Git's data model

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

"Julia Evans" <julia@jvns.ca> writes:

> Like you noticed in the tag object section, I think saying that the tag
> object "refers to an object" works well in that context, but in the context
> of explaining what a branch is it makes the text more confusing.

Sorry, but I do not understand your objection, as I cannot see what
confusion it would bring in in saying "a ref refers to an object"
(or "a branch refers to a commit object").  A ref refers to an
object, just like a tag field in a tag object or a tree-entry in a
tree object refer to another object.  They do so by recording the
name of the object they refer to.  So what's so confusing if we said
that straight?

Are you saying that the noun "reference" (or "ref") is a sufficient
clue to readers that their objective is to "refer to" something, so
"refers to" is a redundant thing to say?

Maybe its just me, but I find it a quite roundabout thing to say
that a ref refers to an object name (or "ID" if you like), simply
because name or ID *is* a way to refer to the thing that is assigned
that name, so you are making a ref to refer to something ("name")
that refers to what it ("ref") originally wanted to refer to
("object").

That is what I find the most strange in the construction "A branch
refers to ID" at the conceptual level.  I am much less unhappy with
"A branch records an ID", but stopping at that may make readers ask
the obvious question "what goal does that design aim to achieve?"
(whose answer is of course "to refer to the object that is assigned
that ID").

"A branch refers to a commit object by recording its object name",
"A branch records the ID of a commit it refers to", "A branch
records the ID of the commit at the tip of its history".  Any of the
phrasing that does not make "ID" the object/target of the verb
"refer to" would work to avoid that strange construction.

By the way, Ben used a word "unwelcome", but the words that are more
appropriate to describe my reaction were "frustrated" (for not being
able to explain what I know to be true clearly to make others
understand) and "disappointed".