undef/git-commit-vandalism
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

doc branch: provide examples for listing remote tracking branches

Browse Source 
The availability of these pattern selections is not obvious from
the man pages, as per mail thread <87lfz3vcbt.fsf@evledraar.gmail.com>.

Provide examples.

Re-order the `git branch` synopsis to emphasise the `--list <pattern>`
pairing. Also expand and reposition the `all/remotes` options.

Split the over-long description into three parts so that the <pattern>
description can be seen.

Clarify that the `all/remotes` options require the --list if patterns
are to be used.

Add examples of listing remote tracking branches that match a pattern,
including `git for-each-ref` which has more options.

Improve the -a/-r warning message. The message confused this author
as the combined -a and -r options had not been given, though a pattern
had. Specifically guide the user that maybe they needed the --list
option to enable a remote branch pattern selection.

Signed-off-by: Philip Oakley <philipoakley@iee.org>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
This commit is contained in:
Philip Oakley 2019-05-29 00:16:05 +01:00 committed by Junio C Hamano
parent aeb582a983
commit 1fde99cfc7
2 changed files with 28 additions and 7 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

32
Documentation/git-branch.txt
View File

@ -8,12 +8,14 @@ git-branch - List, create, or delete branches
SYNOPSIS SYNOPSIS
-------- --------
[verse] [verse]
'git branch' [--color[=<when>] | --no-color] [-r | -a] 'git branch' [--color[=<when>] | --no-color]
[--list] [-v [--abbrev=<length> | --no-abbrev]] [-v [--abbrev=<length> | --no-abbrev]]
[--column[=<options>] | --no-column] [--sort=<key>] [--column[=<options>] | --no-column] [--sort=<key>]
[(--merged | --no-merged) [<commit>]] [(--merged | --no-merged) [<commit>]]
[--contains [<commit]] [--no-contains [<commit>]] [--contains [<commit]] [--no-contains [<commit>]]
[--points-at <object>] [--format=<format>] [<pattern>...] [--points-at <object>] [--format=<format>]
[(-r | --remotes) | (-a | --all)]
[--list] [<pattern>...]
'git branch' [--track | --no-track] [-f] <branchname> [<start-point>] 'git branch' [--track | --no-track] [-f] <branchname> [<start-point>]
'git branch' (--set-upstream-to=<upstream> | -u <upstream>) [<branchname>] 'git branch' (--set-upstream-to=<upstream> | -u <upstream>) [<branchname>]
'git branch' --unset-upstream [<branchname>] 'git branch' --unset-upstream [<branchname>]
@ -28,11 +30,15 @@ DESCRIPTION
If `--list` is given, or if there are no non-option arguments, existing If `--list` is given, or if there are no non-option arguments, existing
branches are listed; the current branch will be highlighted with an branches are listed; the current branch will be highlighted with an
asterisk. Option `-r` causes the remote-tracking branches to be listed, asterisk. Option `-r` causes the remote-tracking branches to be listed,
and option `-a` shows both local and remote branches. If a `<pattern>` and option `-a` shows both local and remote branches.
If a `<pattern>`
is given, it is used as a shell wildcard to restrict the output to is given, it is used as a shell wildcard to restrict the output to
matching branches. If multiple patterns are given, a branch is shown if matching branches. If multiple patterns are given, a branch is shown if
it matches any of the patterns. Note that when providing a it matches any of the patterns.
`<pattern>`, you must use `--list`; otherwise the command is interpreted
Note that when providing a
`<pattern>`, you must use `--list`; otherwise the command may be interpreted
as branch creation. as branch creation.
With `--contains`, shows only the branches that contain the named commit With `--contains`, shows only the branches that contain the named commit
@ -149,10 +155,12 @@ This option is only applicable in non-verbose mode.
-r:: -r::
--remotes:: --remotes::
List or delete (if used with -d) the remote-tracking branches. List or delete (if used with -d) the remote-tracking branches.
Combine with `--list` to match the optional pattern(s).
-a:: -a::
--all:: --all::
List both remote-tracking branches and local branches. List both remote-tracking branches and local branches.
Combine with `--list` to match optional pattern(s).
-l:: -l::
--list:: --list::
@ -314,6 +322,18 @@ $ git branch -D test <2>
<2> Delete the "test" branch even if the "master" branch (or whichever branch <2> Delete the "test" branch even if the "master" branch (or whichever branch
is currently checked out) does not have all commits from the test branch. is currently checked out) does not have all commits from the test branch.
Listing branches from a specific remote::
+
------------
$ git branch -r -l '<remote>/<pattern>' <1>
$ git for-each-ref 'refs/remotes/<remote>/<pattern>' <2>
------------
+
<1> Using `-a` would conflate <remote> with any local branches you happen to
have been prefixed with the same <remote> pattern.
<2> `for-each-ref` can take a wide range of options. See linkgit:git-for-each-ref[1]
Patterns will normally need quoting.
NOTES NOTES
----- -----

3
builtin/branch.c
View File

@ -810,7 +810,8 @@ int cmd_branch(int argc, const char **argv, const char *prefix)
strbuf_release(&buf); strbuf_release(&buf);
} else if (argc > 0 && argc <= 2) { } else if (argc > 0 && argc <= 2) {
if (filter.kind != FILTER_REFS_BRANCHES) if (filter.kind != FILTER_REFS_BRANCHES)
die(_("-a and -r options to 'git branch' do not make sense with a branch name")); die(_("The -a, and -r, options to 'git branch' do not take a branch name.\n"
"Did you mean to use: -a|-r --list <pattern>?"));
if (track == BRANCH_TRACK_OVERRIDE) if (track == BRANCH_TRACK_OVERRIDE)
die(_("the '--set-upstream' option is no longer supported. Please use '--track' or '--set-upstream-to' instead.")); die(_("the '--set-upstream' option is no longer supported. Please use '--track' or '--set-upstream-to' instead."));