Jakub Narebski <jnareb@xxxxxxxxx> 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.
-
: send the line "unsubscribe git" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html