git branch documentation improvements

git branch documentation improvements

[Andreas Hartmetz]

[-- Attachment #1: Type: Text/Plain, Size: 575 bytes --]

Hello all,

Today I read the git branch documentation and noticed a few things, mostly 
style and consistency related, that could easily be improved, so I did just 
that.
Please consider merging the attached patch if it looks good, or tell me what 
you don't like about it.
The most significant change is renaming <start-point> (or is it 
<startpoint>...) to <branch-head> because even I as a relative beginner know 
that a branch is defined by its (movable) head, and <start-point> *does* 
actually specify the new branch head if I'm not mistaken.

Cheers,
Andreas Hartmetz

[-- Attachment #2: git-branch-doc.diff --]
[-- Type: text/x-patch, Size: 5865 bytes --]

diff --git a/Documentation/git-branch.txt b/Documentation/git-branch.txt
index 1940256..872bb3e 100644
--- a/Documentation/git-branch.txt
+++ b/Documentation/git-branch.txt
@@ -11,51 +11,50 @@ SYNOPSIS
 'git branch' [--color[=<when>] | --no-color] [-r | -a]
 	[-v [--abbrev=<length> | --no-abbrev]]
 	[(--merged | --no-merged | --contains) [<commit>]]
-'git branch' [--set-upstream | --track | --no-track] [-l] [-f] <branchname> [<start-point>]
+'git branch' [--set-upstream | --track | --no-track] [-l] [-f] <branchname> [<branch-head>]
 'git branch' (-m | -M) [<oldbranch>] <newbranch>
 'git branch' (-d | -D) [-r] <branchname>...
 
 DESCRIPTION
 -----------
 
-With no arguments, existing branches are listed and the current branch will
-be highlighted with an asterisk.  Option `-r` causes the remote-tracking
-branches to be listed, and option `-a` shows both.
+With no arguments, local branches are listed and the current branch is
+highlighted with an asterisk.  Option `-r` lists remote-tracking
+branches, and option `-a` lists both.
 
-With `--contains`, shows only the branches that contain the named commit
+With `--contains`, show only the branches that contain the named commit
 (in other words, the branches whose tip commits are descendants of the
 named commit).  With `--merged`, only branches merged into the named
 commit (i.e. the branches whose tip commits are reachable from the named
-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).
+commit) are listed.  With `--no-merged` only branches not merged into
+the named commit are listed.  If the <commit> argument is missing it
+defaults to 'HEAD', the tip of the current 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
+The second form of the command creates a new branch head named <branchname>
+which points to the current 'HEAD', or <branch-head> if given.
+Note that this creates the new branch, but does 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 branch, git sets up the
 branch so that 'git pull' will appropriately merge from
 the remote 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.
+`branch.autosetupmerge` configuration flag. You can override the
+flag using the `--track` and `--no-track` options.
 
-With a '-m' or '-M' option, <oldbranch> will be renamed to <newbranch>.
+With the '-m' or '-M' command, <oldbranch> is renamed to <newbranch>.
 If <oldbranch> had a corresponding reflog, it is renamed to match
 <newbranch>, and a reflog entry is created to remember the branch
-renaming. If <newbranch> exists, -M must be used to force the rename
-to happen.
+renaming. If <newbranch> exists, -M can be used to forwe overwriting
+it.
 
-With a `-d` or `-D` option, `<branchname>` will be deleted.  You may
-specify more than one branch for deletion.  If the branch currently
-has a reflog then the reflog will also be deleted.
+With the `-d` or `-D` command, `<branchname>` is deleted.  You may
+specify more than one branch to delete.  If the branch currently
+has a reflog, the reflog is also be deleted.
 
-Use -r together with -d to delete remote-tracking branches. Note, that it
+Use -r together with -d to delete remote-tracking branches. Note that it
 only makes sense to delete remote-tracking branches if they no longer exist
-in the remote repository or if 'git fetch' was configured not to fetch
+in the remote repository, or if 'git fetch' was configured not to fetch
 them again. See also the 'prune' subcommand of linkgit:git-remote[1] for a
 way to clean up all obsolete remote-tracking branches.
 
@@ -79,7 +78,7 @@ OPTIONS
 
 -f::
 --force::
-	Reset <branchname> to <startpoint> if <branchname> exists
+	Reset <branchname> to <branch-head> if <branchname> exists
 	already. Without `-f` 'git branch' refuses to change an existing branch.
 
 -m::
@@ -119,8 +118,8 @@ OPTIONS
 -t::
 --track::
 	When creating a new branch, set up configuration to mark the
-	start-point branch as "upstream" from the new branch. This
-	configuration will tell git to show the relationship between the
+	<branch-head> branch as "upstream" from the new branch. This
+	configuration tells git to show the relationship between the
 	two branches in `git status` and `git branch -v`. Furthermore,
 	it directs `git pull` without arguments to pull from the
 	upstream when the new branch is checked out.
@@ -133,13 +132,13 @@ start-point is either a local or remote branch.
 
 --no-track::
 	Do not set up "upstream" configuration, even if the
-	branch.autosetupmerge configuration variable is true.
+	branch.autosetupmerge configuration flag is true.
 
 --set-upstream::
 	If specified branch does not exist yet or if '--force' has been
 	given, acts exactly like '--track'. Otherwise sets up configuration
 	like '--track' would when creating the branch, except that where
-	branch points to is not changed.
+	<branchname> points to is not changed.
 
 --contains <commit>::
 	Only list branches which contain the specified commit.
@@ -158,7 +157,7 @@ start-point is either a local or remote branch.
 	linkgit:git-check-ref-format[1].  Some of these checks
 	may restrict the characters allowed in a branch name.
 
-<start-point>::
+<branch-head>::
 	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.

Re: git branch documentation improvements

[Jon Seymour]

This patch would be easier to review, and thus more likely to be
accepted, if the guidelines in SubmittingPatches had been followed,
w.r.t. not using attachments to submit patches.


On Fri, May 7, 2010 at 8:24 AM, Andreas Hartmetz <ahartmetz@gmail.com> wrote:
> Hello all,
>
> Today I read the git branch documentation and noticed a few things, mostly
> style and consistency related, that could easily be improved, so I did just
> that.
> Please consider merging the attached patch if it looks good, or tell me what
> you don't like about it.
> The most significant change is renaming <start-point> (or is it
> <startpoint>...) to <branch-head> because even I as a relative beginner know
> that a branch is defined by its (movable) head, and <start-point> *does*
> actually specify the new branch head if I'm not mistaken.
>

While I agree with you start start-point is probably the wrong name
for this parameter, I wonder whether branch-head might be too
suggestive that the value of that parameter must itself be an existing
branch head.

I think the term "head-commit" would be a more accurate way to
describe the possible values of this parameter. That is, it is the
commit that will become the head of the new branch.

jon.

Re: git branch documentation improvements

[Andreas Hartmetz]

On Friday 07 May 2010 00:59:22 Jon Seymour wrote:
> This patch would be easier to review, and thus more likely to be
> accepted, if the guidelines in SubmittingPatches had been followed,
> w.r.t. not using attachments to submit patches.
> 
Oops, sorry. I didn't see that file. Patch follows at the end.

> On Fri, May 7, 2010 at 8:24 AM, Andreas Hartmetz <ahartmetz@gmail.com> wrote:
> > Hello all,
> > 
> > Today I read the git branch documentation and noticed a few things,
> > mostly style and consistency related, that could easily be improved, so
> > I did just that.
> > Please consider merging the attached patch if it looks good, or tell me
> > what you don't like about it.
> > The most significant change is renaming <start-point> (or is it
> > <startpoint>...) to <branch-head> because even I as a relative beginner
> > know that a branch is defined by its (movable) head, and <start-point>
> > *does* actually specify the new branch head if I'm not mistaken.
> 
> While I agree with you start start-point is probably the wrong name
> for this parameter, I wonder whether branch-head might be too
> suggestive that the value of that parameter must itself be an existing
> branch head.
> 
> I think the term "head-commit" would be a more accurate way to
> describe the possible values of this parameter. That is, it is the
> commit that will become the head of the new branch.
> 
Yes, why not.

I noticed a problem in the second paragraph of the description of --track
where neither <start-point> nor <branch-head> nor <head-commit> works well.
Maybe I butchered the first sentence because it used to say "start point".
Either way, that first sentence looks fishy to me.
Any suggestions?

>From 3fa7cb87068cfba00c55f494b30f3773f4ce9c69 Mon Sep 17 00:00:00 2001
From: Andreas Hartmetz <ahartmetz@gmail.com>
Date: Fri, 7 May 2010 02:44:41 +0200
Subject: [PATCH] git-branch documentation improvements:
 - Use only present tense where possible
 - Use similar wording for similar things
 - Miscellaneous style improvements
 - Replace "<start-point>" with "<head-commit>" which is more in line with the
   how git actually works, and applies to all situations

Signed-off-by: Andreas Hartmetz <ahartmetz@gmail.com>
---
 Documentation/git-branch.txt |   61 ++++++++++++++++++++---------------------
 1 files changed, 30 insertions(+), 31 deletions(-)

diff --git a/Documentation/git-branch.txt b/Documentation/git-branch.txt
index 1940256..7878534 100644
--- a/Documentation/git-branch.txt
+++ b/Documentation/git-branch.txt
@@ -11,51 +11,50 @@ SYNOPSIS
 'git branch' [--color[=<when>] | --no-color] [-r | -a]
 	[-v [--abbrev=<length> | --no-abbrev]]
 	[(--merged | --no-merged | --contains) [<commit>]]
-'git branch' [--set-upstream | --track | --no-track] [-l] [-f] <branchname> [<start-point>]
+'git branch' [--set-upstream | --track | --no-track] [-l] [-f] <branchname> [<head-commit>]
 'git branch' (-m | -M) [<oldbranch>] <newbranch>
 'git branch' (-d | -D) [-r] <branchname>...

 DESCRIPTION
 -----------

-With no arguments, existing branches are listed and the current branch will
-be highlighted with an asterisk.  Option `-r` causes the remote-tracking
-branches to be listed, and option `-a` shows both.
+With no arguments, local branches are listed and the current branch is
+highlighted with an asterisk.  Option `-r` lists remote-tracking
+branches, and option `-a` lists both.

-With `--contains`, shows only the branches that contain the named commit
+With `--contains`, show only the branches that contain the named commit
 (in other words, the branches whose tip commits are descendants of the
 named commit).  With `--merged`, only branches merged into the named
 commit (i.e. the branches whose tip commits are reachable from the named
-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).
+commit) are listed.  With `--no-merged` only branches not merged into
+the named commit are listed.  If the <commit> argument is missing it
+defaults to 'HEAD', the tip of the current 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
+The second form of the command creates a new branch head named <branchname>
+which points to the current 'HEAD', or <head-commit> if given.
+Note that this creates the new branch, but does 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 branch, git sets up the
 branch so that 'git pull' will appropriately merge from
 the remote 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.
+`branch.autosetupmerge` configuration flag. You can override the
+flag using the `--track` and `--no-track` options.

-With a '-m' or '-M' option, <oldbranch> will be renamed to <newbranch>.
+With the '-m' or '-M' command, <oldbranch> is renamed to <newbranch>.
 If <oldbranch> had a corresponding reflog, it is renamed to match
 <newbranch>, and a reflog entry is created to remember the branch
-renaming. If <newbranch> exists, -M must be used to force the rename
-to happen.
+renaming. If <newbranch> exists, -M can be used to forwe overwriting
+it.

-With a `-d` or `-D` option, `<branchname>` will be deleted.  You may
-specify more than one branch for deletion.  If the branch currently
-has a reflog then the reflog will also be deleted.
+With the `-d` or `-D` command, `<branchname>` is deleted.  You may
+specify more than one branch to delete.  If the branch currently
+has a reflog, the reflog is also be deleted.

-Use -r together with -d to delete remote-tracking branches. Note, that it
+Use -r together with -d to delete remote-tracking branches. Note that it
 only makes sense to delete remote-tracking branches if they no longer exist
-in the remote repository or if 'git fetch' was configured not to fetch
+in the remote repository, or if 'git fetch' was configured not to fetch
 them again. See also the 'prune' subcommand of linkgit:git-remote[1] for a
 way to clean up all obsolete remote-tracking branches.

@@ -79,7 +78,7 @@ OPTIONS

 -f::
 --force::
-	Reset <branchname> to <startpoint> if <branchname> exists
+	Reset <branchname> to <head-commit> if <branchname> exists
 	already. Without `-f` 'git branch' refuses to change an existing branch.

 -m::
@@ -119,27 +118,27 @@ OPTIONS
 -t::
 --track::
 	When creating a new branch, set up configuration to mark the
-	start-point branch as "upstream" from the new branch. This
-	configuration will tell git to show the relationship between the
+	<head-commit> branch as "upstream" from the new branch. This
+	configuration tells git to show the relationship between the
 	two branches in `git status` and `git branch -v`. Furthermore,
 	it directs `git pull` without arguments to pull from the
 	upstream when the new branch is checked out.
 +
-This behavior is the default when the start point is a remote branch.
-Set the branch.autosetupmerge configuration variable to `false` if you
+This behavior is the default when the <head-commit> is a remote branch.
+Set the branch.autosetupmerge configuration flag to `false` if you
 want `git checkout` and `git branch` to always behave as if '--no-track'
 were given. Set it to `always` if you want this behavior when the
-start-point is either a local or remote branch.
+<head-commit> is either a local or remote branch.

 --no-track::
 	Do not set up "upstream" configuration, even if the
-	branch.autosetupmerge configuration variable is true.
+	branch.autosetupmerge configuration flag is true.

 --set-upstream::
 	If specified branch does not exist yet or if '--force' has been
 	given, acts exactly like '--track'. Otherwise sets up configuration
 	like '--track' would when creating the branch, except that where
-	branch points to is not changed.
+	<branchname> points to is not changed.

 --contains <commit>::
 	Only list branches which contain the specified commit.
@@ -158,7 +157,7 @@ start-point is either a local or remote branch.
 	linkgit:git-check-ref-format[1].  Some of these checks
 	may restrict the characters allowed in a branch name.

-<start-point>::
+<head-commit>::
 	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.
--
1.7.0.4

Re: git branch documentation improvements

[Andreas Hartmetz]

On Friday 07 May 2010 00:59:22 Jon Seymour wrote:
> On Fri, May 7, 2010 at 8:24 AM, Andreas Hartmetz <ahartmetz@gmail.com> 
wrote:
> > Today I read the git branch documentation and noticed a few things,
> > mostly style and consistency related, that could easily be improved, so
> > I did just that.
> > Please consider merging the attached patch if it looks good, or tell me
> > what you don't like about it.
> > The most significant change is renaming <start-point> (or is it
> > <startpoint>...) to <branch-head> because even I as a relative beginner
> > know that a branch is defined by its (movable) head, and <start-point>
> > *does* actually specify the new branch head if I'm not mistaken.
> 
> While I agree with you start start-point is probably the wrong name
> for this parameter, I wonder whether branch-head might be too
> suggestive that the value of that parameter must itself be an existing
> branch head.
> 
> I think the term "head-commit" would be a more accurate way to
> describe the possible values of this parameter. That is, it is the
> commit that will become the head of the new branch.
> 
Another suggestion I came up with much earlier that I recalled just now:
<new-head>

Re: git branch documentation improvements

[Johannes Sixt]

Am 5/7/2010 0:24, schrieb Andreas Hartmetz:
> The most significant change is renaming <start-point> (or is it 
> <startpoint>...) to <branch-head> because even I as a relative beginner know 
> that a branch is defined by its (movable) head, and <start-point> *does* 
> actually specify the new branch head if I'm not mistaken.

But what is wrong with "start-point"? It precisely conveys the meaning of
the parameter.

-- Hannes

Re: git branch documentation improvements

[Jon Seymour]

My minor quibble with start-point is that the naive user may assume
that, like CVS or SVN, git has some persistent notion of a "start
point".

In reality, git only tracks heads. A term like "head-commit" is, IMO,
more precise than "start-point" and does not potentially convey the
false notion that git knows or cares about the point at which a branch
was "started".

jon.

On Fri, May 7, 2010 at 5:20 PM, Johannes Sixt <j.sixt@viscovery.net> wrote:
> Am 5/7/2010 0:24, schrieb Andreas Hartmetz:
>> The most significant change is renaming <start-point> (or is it
>> <startpoint>...) to <branch-head> because even I as a relative beginner know
>> that a branch is defined by its (movable) head, and <start-point> *does*
>> actually specify the new branch head if I'm not mistaken.
>
> But what is wrong with "start-point"? It precisely conveys the meaning of
> the parameter.
>
> -- Hannes
> --
> To unsubscribe from this list: send the line "unsubscribe git" in
> the body of a message to majordomo@vger.kernel.org
> More majordomo info at  http://vger.kernel.org/majordomo-info.html
>

Re: git branch documentation improvements

[Andreas Hartmetz]

On Friday 07 May 2010 09:20:15 Johannes Sixt wrote:
> Am 5/7/2010 0:24, schrieb Andreas Hartmetz:
> > The most significant change is renaming <start-point> (or is it
> > <startpoint>...) to <branch-head> because even I as a relative beginner
> > know that a branch is defined by its (movable) head, and <start-point>
> > *does* actually specify the new branch head if I'm not mistaken.
> 
> But what is wrong with "start-point"? It precisely conveys the meaning of
> the parameter.
> 
Look at -f: as far as I understand it moves the branch *head*, so start-point 
is plain wrong. The "root" of the branch is not moved, or only moved 
indirectly (not sure if the latter is allowed).

Re: git branch documentation improvements

[Johannes Sixt]

Am 5/8/2010 18:39, schrieb Andreas Hartmetz:
> On Friday 07 May 2010 09:20:15 Johannes Sixt wrote:
>> But what is wrong with "start-point"? It precisely conveys the meaning of
>> the parameter.
>>
> Look at -f: as far as I understand it moves the branch *head*, so start-point 
> is plain wrong. The "root" of the branch is not moved, or only moved 
> indirectly (not sure if the latter is allowed).

Huh? The purpose of -f is not to *move* a branch head, but to say "trust
me, I know what I'm doing". Why would "start-point" not be suitable in
this case?

-- Hannes

Re: git branch documentation improvements

[Andreas Hartmetz]

On Monday 10 May 2010 08:22:33 Johannes Sixt wrote:
> Am 5/8/2010 18:39, schrieb Andreas Hartmetz:
> > On Friday 07 May 2010 09:20:15 Johannes Sixt wrote:
> >> But what is wrong with "start-point"? It precisely conveys the meaning
> >> of the parameter.
> > 
> > Look at -f: as far as I understand it moves the branch *head*, so
> > start-point is plain wrong. The "root" of the branch is not moved, or
> > only moved indirectly (not sure if the latter is allowed).
> 
> Huh? The purpose of -f is not to *move* a branch head, but to say "trust
> me, I know what I'm doing". Why would "start-point" not be suitable in
> this case?
> 
Because a branch doesn't start at the head.