git/list[1] front-page[2] threads[3] people[4] search[5] about
 

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

From
Jonathan Nieder <jrnieder@gmail.com>
Date
Oct 9, 2009, 18:34 UTC
Message-ID
<20091009183408.GB2477@progeny.tock>
In-Reply-To
<BLU0-SMTP425A9541141B09D790814EAECB0@phx.gbl>
Sean Estabrooks wrote:
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(-)
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
Previous: Sean EstabrooksNext: Junio C Hamano
Message 14 of 19 in “Documentation tweaks”
  1. 0/9 Documentation tweaksJonathan Nieder, Oct 9, 2009
  2. 1/9 Describe DOCBOOK_XSL_172, ASCIIDOC_NO_ROFF options in MakefileJonathan Nieder, Oct 9, 2009
  3. 2/9 Documentation: git fmt-merge-message is not a scriptJonathan Nieder, Oct 9, 2009
  4. 3/9 Documentation: fix singular/plural mismatchJonathan Nieder, Oct 9, 2009
  5. 4/9 Documentation: say "the same" instead of "equal"Jonathan Nieder, Oct 9, 2009
  6. 4/9 Documentation: clarify mergeoptions descriptionJonathan Nieder, Oct 9, 2009
  7. 5/9 Documentation: clone: clarify discussion of initial branchJonathan Nieder, Oct 9, 2009
  8. Junio C HamanoOct 9, 2009
  9. 5/9 Documentation: clone: clarify discussion of initial branchJonathan Nieder, Oct 9, 2009
  10. 6/9 Documentation: branch: update --merged descriptionJonathan Nieder, Oct 9, 2009
  11. Junio C HamanoOct 10, 2009
  12. 7/9 Documentation: clarify branch creationJonathan Nieder, Oct 9, 2009
  13. Sean EstabrooksOct 9, 2009
  14. Jonathan NiederOct 9, 2009
  15. Junio C HamanoOct 10, 2009
  16. 8/9 Documentation: clarify "working tree" definitionJonathan Nieder, Oct 9, 2009
  17. 9/9 racy-git.txt: explain nsec problem in more detailJonathan Nieder, Oct 9, 2009
  18. Junio C HamanoOct 10, 2009
  19. Junio C HamanoOct 10, 2009

Read the whole thread, see it on lore, or plain text.

$ cat FOOTERMessages come from the public archive at lore.kernel.org/git, fetched every hour. The front page is chosen and written each morning by an AI editor and can be wrong; the threads themselves are the record. About and API. For agents: an MCP server at https://gitlist.dev/mcp, and any thread, story or person page as Markdown by adding .md to its URL (or sending Accept: text/markdown). Details in /llms.txt.