user-manual: introduce "branch" and "branch head" differently
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>
J. Bruce Fields committed
Mar 18, 2007 at 23:02 UTC
81b6c950dede5bca60dac0834de25b6f30ec10bb
1 file changed
+21
-22
Documentation/user-manual.txt
+21
-22
@@ -288,21 +288,22 @@ collection of files. It stores the history as a compressed
288
collection of interrelated snapshots (versions) of the project's
289
contents.
290
291
-A single git repository may contain multiple branches. Each branch
292
-is a bookmark referencing a particular point in the project history.
293
-The gitlink:git-branch[1] command shows you the list of branches:
291
+A single git repository may contain multiple branches. It keeps track
292
+of them by keeping a list of <<def_head,heads>> which reference the
293
+latest version on each branch; the gitlink:git-branch[1] command shows
294
+you the list of branch heads:
295
296
------------------------------------------------
297
$ git branch
298
* master
299
------------------------------------------------
300
300
-A freshly cloned repository contains a single branch, named "master",
301
-and the working directory contains the version of the project
302
-referred to by the master branch.
301
+A freshly cloned repository contains a single branch head, named
302
+"master", and working directory is initialized to the state of
303
+the project referred to by "master".
304
304
-Most projects also use tags. Tags, like branches, are references
305
-into the project's history, and can be listed using the
305
+Most projects also use <<def_tag,tags>>. Tags, like heads, are
306
+references into the project's history, and can be listed using the
307
gitlink:git-tag[1] command:
308
309
------------------------------------------------
@@ -320,9 +321,9 @@ v2.6.13
321
------------------------------------------------
322
323
Tags are expected to always point at the same version of a project,
323
-while branches are expected to advance as development progresses.
324
+while heads are expected to advance as development progresses.
325
325
-Create a new branch pointing to one of these versions and check it
326
+Create a new branch head pointing to one of these versions and check it
327
out using gitlink:git-checkout[1]:
328
329
------------------------------------------------
@@ -346,10 +347,10 @@ the current branch to point at v2.6.17 instead, with
347
$ git reset --hard v2.6.17
348
------------------------------------------------
349
349
-Note that if the current branch was your only reference to a
350
+Note that if the current branch head was your only reference to a
351
particular point in history, then resetting that branch may leave you
351
-with no way to find the history it used to point to; so use this
352
-command carefully.
352
+with no way to find the history it used to point to; so use this command
353
+carefully.
354
355
Understanding History: Commits
356
------------------------------
@@ -452,17 +453,15 @@ be replaced with another letter or number.
453
Understanding history: What is a branch?
454
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
455
455
-Though we've been using the word "branch" to mean a kind of reference
456
-to a particular commit, the word branch is also commonly used to
457
-refer to the line of commits leading up to that point. In the
458
-example above, git may think of the branch named "A" as just a
459
-pointer to one particular commit, but we may refer informally to the
460
-line of three commits leading up to that point as all being part of
456
+When we need to be precise, we will use the word "branch" to mean a line
457
+of development, and "branch head" (or just "head") to mean a reference
458
+to the most recent commit on a branch. In the example above, the branch
459
+head named "A" is a pointer to one particular commit, but we refer to
460
+the line of three commits leading up to that point as all being part of
461
"branch A".
462
463
-If we need to make it clear that we're just talking about the most
464
-recent commit on the branch, we may refer to that commit as the
465
-"head" of the branch.
463
+However, when no confusion will result, we often just use the term
464
+"branch" both for branches and for branch heads.
465
466
Manipulating branches
467
---------------------