[PATCH] Documentation update for 'git branch --list'

[PATCH] Documentation update for 'git branch --list'

[Vincent van Ravesteijn]

Indicate that the <pattern>... argument is only valid when using --list.
Otherwise a branch with the name <pattern> will be created. The current
synopsis also suggests that 'git branch -d <pattern>...' would be a valid
command.

Minor changes:
- add a period to a sentence,
- change tag into branch.

Signed-off-by: Vincent van Ravesteijn <vfr@lyx.org>
---
 Documentation/git-branch.txt |   11 ++++++-----
 1 files changed, 6 insertions(+), 5 deletions(-)

diff --git a/Documentation/git-branch.txt b/Documentation/git-branch.txt
index f46013c..9f49db4 100644
--- a/Documentation/git-branch.txt
+++ b/Documentation/git-branch.txt
@@ -9,8 +9,9 @@ SYNOPSIS
 --------
 [verse]
 'git branch' [--color[=<when>] | --no-color] [-r | -a]
-	[--list] [-v [--abbrev=<length> | --no-abbrev]]
-	[(--merged | --no-merged | --contains) [<commit>]] [<pattern>...]
+	[-v [--abbrev=<length> | --no-abbrev]]
+	[(--merged | --no-merged | --contains) [<commit>]]
+	[--list [<pattern>...]]
 'git branch' [--set-upstream | --track | --no-track] [-l] [-f] <branchname> [<start-point>]
 'git branch' (-m | -M) [<oldbranch>] <newbranch>
 'git branch' (-d | -D) [-r] <branchname>...
@@ -23,8 +24,8 @@ be highlighted with an asterisk.  Option `-r` causes the remote-tracking
 branches to be listed, and option `-a` shows both. This list mode is also
 activated by the `--list` option (see below).
 <pattern> restricts the output to matching branches, the pattern is a shell
-wildcard (i.e., matched using fnmatch(3))
-Multiple patterns may be given; if any of them matches, the tag is shown.
+wildcard (i.e., matched using fnmatch(3)).
+Multiple patterns may be given; if any of them matches, the branch is shown.
 
 With `--contains`, shows only the branches that contain the named commit
 (in other words, the branches whose tip commits are descendants of the
@@ -114,7 +115,7 @@ OPTIONS
 --all::
 	List both remote-tracking branches and local branches.
 
---list::
+--list [<pattern>...]::
 	Activate the list mode. `git branch <pattern>` would try to create a branch,
 	use `git branch --list <pattern>` to list matching branches.
 
-- 
1.7.4.1

Re: [PATCH] Documentation update for 'git branch --list'

[Vincent van Ravesteijn]

> The current synopsis also suggests that 'git branch -d<pattern>...'
> would be a valid command.

Well.. that's a lie.

Vincent

Re: [PATCH] Documentation update for 'git branch --list'

[Junio C Hamano]

Vincent van Ravesteijn <vfr@lyx.org> writes:

> Indicate that the <pattern>... argument is only valid when using --list.
> Otherwise a branch with the name <pattern> will be created.

I actually think there are some bugs in the implementation along that line
and the way forward is to fix the implementation, instead of documenting
the buggy behaviour.

It is natural to expect "git branch --merged pu vr/\*" to list branches
that are contained in 'pu' whose names match the given pattern, but it
seems to try creating a branch called "vr/*" and fails, for example.

> The current
> synopsis also suggests that 'git branch -d <pattern>...' would be a valid
> command.

That is not how I read the current synopsis for -d; doesn't it avoid using
<pattern> and explicitly say <branchname>?

> Signed-off-by: Vincent van Ravesteijn <vfr@lyx.org>
> ---
>  Documentation/git-branch.txt |   11 ++++++-----
>  1 files changed, 6 insertions(+), 5 deletions(-)
>
> diff --git a/Documentation/git-branch.txt b/Documentation/git-branch.txt
> index f46013c..9f49db4 100644
> --- a/Documentation/git-branch.txt
> +++ b/Documentation/git-branch.txt
> @@ -9,8 +9,9 @@ SYNOPSIS
>  --------
>  [verse]
>  'git branch' [--color[=<when>] | --no-color] [-r | -a]
> -	[--list] [-v [--abbrev=<length> | --no-abbrev]]
> -	[(--merged | --no-merged | --contains) [<commit>]] [<pattern>...]
> +	[-v [--abbrev=<length> | --no-abbrev]]
> +	[(--merged | --no-merged | --contains) [<commit>]]
> +	[--list [<pattern>...]]
>  'git branch' [--set-upstream | --track | --no-track] [-l] [-f] <branchname> [<start-point>]
>  'git branch' (-m | -M) [<oldbranch>] <newbranch>
>  'git branch' (-d | -D) [-r] <branchname>...
> @@ -23,8 +24,8 @@ be highlighted with an asterisk.  Option `-r` causes the remote-tracking
>  branches to be listed, and option `-a` shows both. This list mode is also
>  activated by the `--list` option (see below).
>  <pattern> restricts the output to matching branches, the pattern is a shell
> -wildcard (i.e., matched using fnmatch(3))
> -Multiple patterns may be given; if any of them matches, the tag is shown.
> +wildcard (i.e., matched using fnmatch(3)).
> +Multiple patterns may be given; if any of them matches, the branch is shown.
>  
>  With `--contains`, shows only the branches that contain the named commit
>  (in other words, the branches whose tip commits are descendants of the
> @@ -114,7 +115,7 @@ OPTIONS
>  --all::
>  	List both remote-tracking branches and local branches.
>  
> ---list::
> +--list [<pattern>...]::
>  	Activate the list mode. `git branch <pattern>` would try to create a branch,
>  	use `git branch --list <pattern>` to list matching branches.

Re: [PATCH] Documentation update for 'git branch --list'

[Vincent van Ravesteijn]

Op 21-11-2011 18:37, Junio C Hamano schreef:
> Vincent van Ravesteijn<vfr@lyx.org>  writes:
>
>> Indicate that the<pattern>... argument is only valid when using --list.
>> Otherwise a branch with the name<pattern>  will be created.
> I actually think there are some bugs in the implementation along that line
> and the way forward is to fix the implementation, instead of documenting
> the buggy behaviour.
>
> It is natural to expect "git branch --merged pu vr/\*" to list branches
> that are contained in 'pu' whose names match the given pattern, but it
> seems to try creating a branch called "vr/*" and fails, for example.

If this is what you naturally would expect, I would expect the following 
"git branch vr/*" to work as well.

What would you say if we try to interpret the argument as a pattern when 
the argument is not a valid ref name ? This includes all arguments 
containing '*'. In case of confusion we can demand the "--list" 
parameter to make clear what we mean.

Another thing is noticed is that the pattern use is different for 'git 
for-each-ref <pattern...>' and 'git branch --list <pattern...>'.

Two examples:

> c:\Users\Vincent\Documents\git\git>git for-each-ref refs/heads/
> f56ef114eeefee755f422e6cbef2d83974cb90f1 commit refs/heads/master
> c2ee0c73bcb4d1980e5d0bb0d20912b565d8ae38 commit refs/heads/next
> e341d009b2e0374520ac72973c6e98d315218624 commit refs/heads/pu
> 5fd37a7da3df644a85887051ae36117c732d1781 commit refs/heads/vr/fix-crashes
> cec815158934d82cdef815ea1342be2c3edbc5c8 commit 
> refs/heads/vr/msvc-compile-fix
> 777963bd4a9f41ac3eae8de2a7b7177917d127e6 commit 
> refs/heads/vr/msvc-compile-fix-poll
>
> c:\Users\Vincent\Documents\git\git>git branch --list refs/heads/
>
> c:\Users\Vincent\Documents\git\git>

and

> c:\Users\Vincent\Documents\git\git>git branch --list v*
>   vr/fix-crashes
>   vr/msvc-compile-fix
>   vr/msvc-compile-fix-poll
>
> c:\Users\Vincent\Documents\git\git>git for-each-ref v*
>
> c:\Users\Vincent\Documents\git\git>


Vincent

Re: [PATCH] Documentation update for 'git branch --list'

[Junio C Hamano]

Vincent van Ravesteijn <vfr@lyx.org> writes:

> Op 21-11-2011 18:37, Junio C Hamano schreef:
> ...
>> It is natural to expect "git branch --merged pu vr/\*" to list branches
>> that are contained in 'pu' whose names match the given pattern, but it
>> seems to try creating a branch called "vr/*" and fails, for example.
>
> If this is what you naturally would expect, I would expect the
> following "git branch vr/*" to work as well.
> What would you say if we try to interpret the argument as a pattern
> when the argument is not a valid ref name?

We don't, as that is inviting mistakes. "git branch vr/*" if you have a
vr/ directory in your working tree may create vr/a branch from where the
tip of vr/b points at by mistake.

The "--merged" option is an explicit clue that the user is not interested
in creating new branch, and the string being a pattern is additional clue.
The "--list" option was recently added for the explicit purpose of giving
such a clue as safety measure.

Re: [PATCH] Documentation update for 'git branch --list'

[Vincent van Ravesteijn]

Op 22-11-2011 19:04, Junio C Hamano schreef:
> Vincent van Ravesteijn<vfr@lyx.org>  writes:
>
>> Op 21-11-2011 18:37, Junio C Hamano schreef:
>> ...
>>> It is natural to expect "git branch --merged pu vr/\*" to list branches
>>> that are contained in 'pu' whose names match the given pattern, but it
>>> seems to try creating a branch called "vr/*" and fails, for example.
>> If this is what you naturally would expect, I would expect the
>> following "git branch vr/*" to work as well.
>> What would you say if we try to interpret the argument as a pattern
>> when the argument is not a valid ref name?
> We don't, as that is inviting mistakes. "git branch vr/*" if you have a
> vr/ directory in your working tree may create vr/a branch from where the
> tip of vr/b points at by mistake.
>
> The "--merged" option is an explicit clue that the user is not interested
> in creating new branch, and the string being a pattern is additional clue.
> The "--list" option was recently added for the explicit purpose of giving
> such a clue as safety measure.

Well, that was the answer that I foresaw.

I will compose a patch implementing an at least consistent behaviour.

Vincent