patchDocumentation update for 'git branch --list'

> 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.

> 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.

> 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>

> 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>

> 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?

> 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.