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

From: David Kågedal <[email-masked]>
Date: Fri, 19 May 2006 08:53:37 +0200

Jakub Narebski <[email-masked]> 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/`.

[...]

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

But the definition of 'branch' in git is quite different from the
definition in CVS or many other systems.  It CVS, each revision
(commit) belongs to a branch, and the branch is a linear sequence of
revisions, not a full DAG.  In git, a commit doesn't really "belong"
in any specific branch.

So, while it makes sense to describe branches as "lines of
development" in general terms, it is also important to note the
specific meaning of 'branch' in the context of git; i.e. as the
history of a single head commit.

I noticed that some of this seems to be changing slightly with the
introduction of branch logs, but I don't know how those are supposed
to be used yet.

-- 
David Kågedal