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

[Jakub Narebski <jnareb@gmail.com>]

Junio C Hamano wrote:

> Jakub Narebski <jnareb@gmail.com> writes:

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

[cut long description]

The description you gave is nice, but it belongs in Tutorial rather than in
Glossary. Additionally it mainly deals with branches fron the 'revision
history' point of view, although the 'commit' point of view can also be
seen.

Glossary entry should be short, up to the point, and encompass al three
points of view: 

 a.) conceptual point of view, i.e. "branch is separate line of
development" (be it stable or development direction, introducing new
feature aka. 'topic', or following aka. 'tracking' changes in other
repository),

 b) revision history point of view, i.e. "on branch means, roughly,
reachable from branch head aka. tip", or "branch is lineage of history of
project" (somewhat mudded by merges[*1*], fork points[*2*] and multiple
roots). This is what current glossary entry tries to present,

 c) commit point of view, i.e. "branch tip is where we do commit
changes" (branch tip is [one of] parent(s) of current commit, and branch
tip is advanced to new commit).


[*1*] Problem with merges:
   
   ---.---.---A-\--.---.---.---B-- branch1
                 \
   ---.---.---C---*D---.---.---E-- branch2   
   
Does A belong to branch2? It is one of parents of commit D. We can assume
that only first parent in merges continues branch. But what if we have the
following history:

   ---.---.---A-\  <---- there was branch1 here
                 \
   ---.---.---C---*D---.---.---E-- branch2 

To which branch belongs A then?


[*2*] Problem with fork point

           /--1---2---3-- maintenance/stable/fixes branch  
          /
  ---A---B----C---D---E-- master/development branch

Following the ancestry chain we get that commit A is on branch 'maint' (it
is also on branch 'master'); git does not record fork points. Perhaps the
branch logging and/or per branch configuration could be used to resolve
this issue.

-- 
Jakub Narebski
Warsaw, Poland