Re: [PATCH] Documentation update for 'git branch --list'
- From
Junio C Hamano <gitster@pobox.com>
- Date
- Nov 21, 2011, 17:37 UTC
- Message-ID
- <7v7h2tgyw6.fsf@alter.siamese.dyndns.org>
- In-Reply-To
- <1321886000-4163-1-git-send-email-vfr@lyx.org>
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>?
Show 40 quoted lines
> 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.