Re: [PATCH 7/9] Documentation: clarify branch creation

Sean Estabrooks wrote:

On Fri, 9 Oct 2009 05:19:40 -0500
Jonathan Nieder [off-list ref] wrote:

quoted

+In the command's second form, creates a new branch named <branchname>.
+The branch will start out with head pointing to the commit
+<start-point>.  If no <start-point> is given, the branch will start
+out with head pointing to the tip of the currently checked out branch,
+or the currently checked out commit if no branch is checked out.

The first sentence here doesn't quite work, perhaps drop the "In".  But
the whole thing is a bit verbose, what about just:

The command's second form creates a new branch named <branchname> which
points to the current HEAD or <start-point> if given.

Makes sense.  I modified this slightly to “new branch head” since the
branch itself does not point to anything.

quoted

 <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 currently checked out branch head
+	is used, or the current commit if no branch is checked
+	out.

Maybe it's not worth worrying about, but couldn't the last sentence
be just:

   If this option is omitted, the current HEAD will be used instead.

That sounds better, thanks.  The reader that does not know what HEAD is
probably needs to read the relevant section of the user manual for other
reasons anyway.

So this page should probably point to the what-is-a-branch section of
the User's Manual.  Maybe something like this?

-- %< --
Subject: 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 <redacted>
---
 Documentation/git-branch.txt |   16 ++++++++--------
 1 files changed, 8 insertions(+), 8 deletions(-)

diff --git a/Documentation/git-branch.txt b/Documentation/git-branch.txt
index e8b32a2..f766b4d 100644
--- a/Documentation/git-branch.txt
+++ b/Documentation/git-branch.txt

@@ -30,10 +30,8 @@ commit) will be listed.  With `--no-merged` only branches not merged into
 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

@@ -149,9 +147,9 @@ start-point is either a local or remote branch.
 	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.

@@ -216,7 +214,9 @@ SEE ALSO
 --------
 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
 ------

-- 
1.6.5.rc1.199.g596ec