Re: [PATCH 7/9] Documentation: clarify branch creation
Show 14 quoted lines
> On Fri, 9 Oct 2009 05:19:40 -0500
> Jonathan Nieder <jrnieder@gmail.com> wrote:
>
> > +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.
Show 14 quoted lines
> > <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 <jrnieder@gmail.com>
---
Documentation/git-branch.txt | 16 ++++++++--------
1 files changed, 8 insertions(+), 8 deletions(-)
Show changes to Documentation/git-branch.txt +8 −8
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
Jonathan Nieder
