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

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

Junio C Hamano <gitster@pobox.com> writes:

> If we do not hesitate using a new word and introduce "label", "a
> branch works as a label for a commit object" may probably work,
> probably.

Another thing.

Do we want to limit the definition of "branch" very narrowly, i.e.,
"subset of refs whose refname begins with refs/heads/"?  

Or do we want to give a description at a bit higher conceptual
level, something like:

  A branch is a mechanism to help you grow one line of history (in
  the sea/cloud of commits) by (1) keeping track of the commit it
  currently is at (by recording its ID in the ref used to implement
  the branch), (2) allowing you easily record a new commit you
  create while you are on it as a child of the current commit (by
  allowing the symbolic ref "HEAD" to point the ref used to
  implement the branch), (3) keeping the description of the theme of
  the particular line of history being developed there (by using
  "branch.<name>.description" configuration variable for the branch)
  which is incorporated when the branch gets merged to an
  integration branch, and (4) keeping track of how the branch has
  grown over time (in the reflog for the ref used to implement the
  branch).

We can limit ourselves to view a "branch" as a narrow subset of a
ref that can point at a single commit in the dag of commits, and it
can be updated at any time to point another different commit that
has no relation to the previous commit.

Once we stop limiting ourselves and explain the purpose of using a
"branch", "it can be updated to point any random commit" stops being
entirely true.  While the "git branch -f" command can be used to do
so, doing so all the time would go against what makes a branch a
branch, i.e. to keep track of the process of growing the history,
and it is expected that it would be a lot more common for the commit
pointed at by the branch ref to move by growing the history with
"git commit", refining the history with "git rebase", etc.  But that
can only follow if readers understand the branch as more than "just
a ref whose name begins with refs/heads/".

I am not sure what level the data model description you are writing
should be at.  The current description seems to concentrate too
narrowly on "a branch is a specialization of a ref" aspect, and
while it is not incorrect as a description of a building block of a
tool set to implement a workflow, it might be too limiting to form
a proper mental model.  I dunno.