Skip to content

Commit

Permalink
user-manual: introduce "branch" and "branch head" differently
Browse files Browse the repository at this point in the history
I was using "branch" to mean "head", but that's perhaps a little
sloppy; so instead start by using the terms "branch head" and "head",
while still quickly falling back on "branch", since that's what
people actually say more frequently.

Also include glossary references on the first uses of "head" and "tag".

Signed-off-by: "J. Bruce Fields" <bfields@citi.umich.edu>
  • Loading branch information
J. Bruce Fields committed Mar 19, 2007
1 parent cbd9192 commit 81b6c95
Showing 1 changed file with 21 additions and 22 deletions.
43 changes: 21 additions & 22 deletions Documentation/user-manual.txt
Original file line number Diff line number Diff line change
Expand Up @@ -288,21 +288,22 @@ collection of files. It stores the history as a compressed
collection of interrelated snapshots (versions) of the project's
contents.

A single git repository may contain multiple branches. Each branch
is a bookmark referencing a particular point in the project history.
The gitlink:git-branch[1] command shows you the list of branches:
A single git repository may contain multiple branches. It keeps track
of them by keeping a list of <<def_head,heads>> which reference the
latest version on each branch; the gitlink:git-branch[1] command shows
you the list of branch heads:

------------------------------------------------
$ git branch
* master
------------------------------------------------

A freshly cloned repository contains a single branch, named "master",
and the working directory contains the version of the project
referred to by the master branch.
A freshly cloned repository contains a single branch head, named
"master", and working directory is initialized to the state of
the project referred to by "master".

Most projects also use tags. Tags, like branches, are references
into the project's history, and can be listed using the
Most projects also use <<def_tag,tags>>. Tags, like heads, are
references into the project's history, and can be listed using the
gitlink:git-tag[1] command:

------------------------------------------------
Expand All @@ -320,9 +321,9 @@ v2.6.13
------------------------------------------------

Tags are expected to always point at the same version of a project,
while branches are expected to advance as development progresses.
while heads are expected to advance as development progresses.

Create a new branch pointing to one of these versions and check it
Create a new branch head pointing to one of these versions and check it
out using gitlink:git-checkout[1]:

------------------------------------------------
Expand All @@ -346,10 +347,10 @@ the current branch to point at v2.6.17 instead, with
$ git reset --hard v2.6.17
------------------------------------------------

Note that if the current branch was your only reference to a
Note that if the current branch head was your only reference to a
particular point in history, then resetting that branch may leave you
with no way to find the history it used to point to; so use this
command carefully.
with no way to find the history it used to point to; so use this command
carefully.

Understanding History: Commits
------------------------------
Expand Down Expand Up @@ -452,17 +453,15 @@ be replaced with another letter or number.
Understanding history: What is a branch?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Though we've been using the word "branch" to mean a kind of reference
to a particular commit, the word branch is also commonly used to
refer to the line of commits leading up to that point. In the
example above, git may think of the branch named "A" as just a
pointer to one particular commit, but we may refer informally to the
line of three commits leading up to that point as all being part of
When we need to be precise, we will use the word "branch" to mean a line
of development, and "branch head" (or just "head") to mean a reference
to the most recent commit on a branch. In the example above, the branch
head named "A" is a pointer to one particular commit, but we refer to
the line of three commits leading up to that point as all being part of
"branch A".

If we need to make it clear that we're just talking about the most
recent commit on the branch, we may refer to that commit as the
"head" of the branch.
However, when no confusion will result, we often just use the term
"branch" both for branches and for branch heads.

Manipulating branches
---------------------
Expand Down

0 comments on commit 81b6c95

Please sign in to comment.