[PATCH 2/2] Documentation/branch: briefly explain what a branch is

[Jonathan Nieder <jrnieder@gmail.com>]

The new reader might not know what git refs are, that history is a
graph, the distinction between local, remote-tracking, and remote
branches, or how to visualize what is going on.  After this change,
those things are still probably not evident but at least there is an
early reminder of some of it.

Also explain how to create a branch before explaining how to list
them.  Based roughly on the description of v0.99.1~53 (Add "git
branch" script, 2005-07-11).

Signed-off-by: Jonathan Nieder <jrnieder@gmail.com>
---
 Documentation/git-branch.txt |   35 ++++++++++++++++++++---------------
 1 files changed, 20 insertions(+), 15 deletions(-)

diff --git a/Documentation/git-branch.txt b/Documentation/git-branch.txt
index d3eeb94..abad7ba 100644
--- a/Documentation/git-branch.txt
+++ b/Documentation/git-branch.txt
@@ -18,6 +18,26 @@ SYNOPSIS
 DESCRIPTION
 -----------
 
+Branches are references to commit objects, representing the tip of a
+line of history.  The branch you are working on is referred to
+by HEAD and the corresponding reference is updated each time
+linkgit:git-commit[1] or linkgit:git-merge[1] makes a new commit.
+
+'git branch' <branchname> [<start-point>]::
+	Creates a new branch named `<branchname>`.
+	If a starting point is specified, that will be where the branch
+	is created; otherwise, the new branch points to the `HEAD` commit.
++
+This will create a new branch, but it does not switch the working tree
+to it.  Use "git checkout <newbranch>" to start working on the new branch.
+
+When a local branch is started off a remote-tracking branch, git sets up the
+branch so that 'git pull' will appropriately merge from
+the remote-tracking branch. This behavior may be changed via the global
+`branch.autosetupmerge` configuration flag. That setting can be
+overridden by using the `--track` and `--no-track` options, and
+changed later using `git branch --set-upstream`.
+
 'git branch' [-r | -a]::
 	With no arguments, existing branches are listed and the current
 	branch will be highlighted with an asterisk.
@@ -34,21 +54,6 @@ DESCRIPTION
 	commit will be listed.  If the <commit> argument is missing it
 	defaults to 'HEAD' (i.e.  the tip of the current branch).
 
-'git branch' <branchname> [<start-point>]::
-	The command's second form creates a new branch head named <branchname>
-	which points to the current 'HEAD', or <start-point> if given.
-+
-Note that this will create the new branch, but it will not switch the
-working tree to it; use "git checkout <newbranch>" to switch to the
-new branch.
-+
-When a local branch is started off a remote-tracking branch, git sets up the
-branch so that 'git pull' will appropriately merge from
-the remote-tracking branch. This behavior may be changed via the global
-`branch.autosetupmerge` configuration flag. That setting can be
-overridden by using the `--track` and `--no-track` options, and
-changed later using `git branch --set-upstream`.
-
 'git branch' (-m | -M) <oldbranch> <newbranch>::
 	With a '-m' or '-M' option, <oldbranch> will be renamed to <newbranch>.
 	If <oldbranch> had a corresponding reflog, it is renamed to match
-- 
1.7.4.rc3