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

[Jakub Narebski <jnareb@gmail.com>]

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? 

Let's take a look at other definitions:

  In software engineering, 'branch' is a separate line of development, which 
  among others allows development on a project to diverge in two directions, 
  such as a stable and a development version. (WikiPedia:Branch)

  In the CVS team development environment, a separate line of development 
  where changes can be isolated. When a programmer changes files on 
  a branch, those changes do not appear on the main trunk 
  or other branches. (cvs.info)

So from the user's point of view, 'branch' is simply _named line of
development_. Refer to topic and tracking branches.

>From the point of view of commit, current branch (or rather branch
head/branch tip) is the place where we attach current development line
(current commit has current head as parent, and head is advanced to the
current commit), something akin to 'top' pointer for stack implemented as
linked list.

ONLY from the point of view of HISTORY, branch define "non-cyclical graph of
revisions, i.e. the complete history of a particular revision, which is
called the branch head." Merges somewhat obscure the branches (as history),
unless for example we assume that first parent is on the same branch, or
use note header to mark appropriate parent/commit. Also git does not record
where branch started... New branch commit logging proposal, and per-branch
configuration should help with these issues.


No concrete proposal for git glossary update...

-- 
Jakub Narebski
Warsaw, Poland