Commits

Anonymous committed bb35f35

Documentation: clarify branch creation

The documentation seems to assume that the starting point for a new
branch is the tip of an existing (ordinary) branch, but that is not
the most common case. More often, "git branch" is used to begin
a branch from a remote-tracking branch, a tag, or an interesting
commit (e.g. origin/pu^2). Clarify the language so it can apply
to these cases. Thanks to Sean Estabrooks for the wording.

Also add a pointer to the user's manual for the bewildered.

Signed-off-by: Jonathan Nieder <jrnieder@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>

Comments (0)

Files changed (1)

Documentation/git-branch.txt

 the named commit will be listed.  If the <commit> argument is missing it
 defaults to 'HEAD' (i.e. the tip of the current branch).
 
-In the command's second form, a new branch named <branchname> will be created.
-It will start out with a head equal to the one given as <start-point>.
-If no <start-point> is given, the branch will be created with a head
-equal to that of the currently checked out branch.
+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
 	may restrict the characters allowed in a branch name.
 
 <start-point>::
-	The new branch will be created with a HEAD equal to this.  It may
-	be given as a branch name, a commit-id, or a tag.  If this option
-	is omitted, the current branch is assumed.
+	The new branch head will point to this commit.  It may be
+	given as a branch name, a commit-id, or a tag.  If this
+	option is omitted, the current HEAD will be used instead.
 
 <oldbranch>::
 	The name of an existing branch to rename.
 --------
 linkgit:git-check-ref-format[1],
 linkgit:git-fetch[1],
-linkgit:git-remote[1].
+linkgit:git-remote[1],
+link:user-manual.html#what-is-a-branch[``Understanding history: What is
+a branch?''] in the Git User's Manual.
 
 Author
 ------