Re: [RFD] Git glossary: 'branch' and 'head' description

[Junio C Hamano <junkio@cox.net>]

Jakub Narebski <jnareb@gmail.com> writes:

> In #git channel somebody asked about 'branches' and 'heads' and was referred
> to the glossary. I had taken then a look at appropriate glossary entries.
>
> In 'Documentation/glossary.txt' we have:
> ----  
> branch::
>         A non-cyclical graph of revisions, i.e. the complete history of
>         a particular revision, which is called the branch head. The
>         branch heads are stored in `$GIT_DIR/refs/heads/`.
>
> head::
>         The top of a branch. It contains a ref to the corresponding
>         commit object.
>
> head ref::
>         A ref pointing to a head. Often, this is abbreviated to "head".
>         Head refs are stored in `$GIT_DIR/refs/heads/`.
>
> revision::
>         A particular state of files and directories which was stored in
>         the object database. It is referenced by a commit object.
> ---- 
>
> It is just me or the glossary entry for `branch` is unnecessary 
> complicated? 

While technically it might be correct, the above description for
"branch" completely misses the point in the context of other
entries.  I do not recall when this entry was first written, but
I suspect it probably predates other entries that talk about the
same thing.

As you point out it talks primarily about the mesh of all
possible histories (i.e commit DAG), without talking much about
what "branch" means and what role "branch" plays.

I cannot easily do a glossary entry to describe that specific
term, but maybe somebody else can split the following up and
paraphrase.

        A project history is born by recording a particular
        state ("revision") as a root commit, and built up by
        recording subsequent states ("revisions") on top of the
        previous commits.  Thus, a group of commits connected by
        their parent fields form a directed acyclic graph
        ("DAG").  Often this linkage between commits by their
        parent fields is called "ancestry chain", and a commit
        that has another commit in its "parent" field is called
        a "child commit" of the latter.

        There can be multiple root commits in the history of a
        project.  In other words, projects born independently
        can later be glued together to become a single project.

        The history is grown by building on top of previous
        commits, and by the nature of distributed development,
        many lineages of histories are grown simultaneously.
        Each lineage is called a "branch".

        A commit that can be reached by following the ancestry
        chain from a commit that is "on the branch" is also "on
        the branch", and a commit that cannot be reached by
        following the ancestry chain from any commit that is "on
        the branch" is not "on the branch".  The commit that
        bootstraps this recursive definition of "on the branch"
        is called its "branch head", the "tip of the branch", or
        the "top commit".  In other words, it is topologically
        the latest commit on the branch.

	The above does not mean the top commit of a branch does
	not have any child commit in the global project
	histories.  It just means that these children are not on
	the branch; they may be on some other branches, forked
	from it.  To create a branch whose "on the branch"
	commits are strict superset of "on the branch" commits
	of another branch is called "forking" the branch.