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

From

Jonathan Nieder <jrnieder@gmail.com>

Date

Jan 30, 2011, 21:35 UTC

Message-ID

<20110130213510.GC10039@burratino>

In-Reply-To

<20110130213258.GA10039@burratino>

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