diff options
authorPhilip Oakley <>2019-05-28 23:16:05 (GMT)
committerJunio C Hamano <>2019-05-29 17:36:16 (GMT)
commit1fde99cfc766353237ff1ca4829ba8d71ccebc87 (patch)
parentaeb582a98374c094361cba1bd756dc6307432c42 (diff)
doc branch: provide examples for listing remote tracking branches
The availability of these pattern selections is not obvious from the man pages, as per mail thread <>. 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 <> Signed-off-by: Junio C Hamano <>
2 files changed, 28 insertions, 7 deletions
diff --git a/Documentation/git-branch.txt b/Documentation/git-branch.txt
index 3bd83a7..c57f6a1 100644
--- a/Documentation/git-branch.txt
+++ b/Documentation/git-branch.txt
@@ -8,12 +8,14 @@ git-branch - List, create, or delete branches
-'git branch' [--color[=<when>] | --no-color] [-r | -a]
- [--list] [-v [--abbrev=<length> | --no-abbrev]]
+'git branch' [--color[=<when>] | --no-color]
+ [-v [--abbrev=<length> | --no-abbrev]]
[--column[=<options>] | --no-column] [--sort=<key>]
[(--merged | --no-merged) [<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' (--set-upstream-to=<upstream> | -u <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
branches are listed; the current branch will be highlighted with an
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
matching branches. If multiple patterns are given, a branch is shown if
-it matches any of the patterns. Note that when providing a
-`<pattern>`, you must use `--list`; otherwise the command is interpreted
+it matches any of the patterns.
+Note that when providing a
+`<pattern>`, you must use `--list`; otherwise the command may be interpreted
as branch creation.
With `--contains`, shows only the branches that contain the named commit
@@ -149,10 +155,12 @@ This option is only applicable in non-verbose mode.
List or delete (if used with -d) the remote-tracking branches.
+ Combine with `--list` to match the optional pattern(s).
List both remote-tracking branches and local branches.
+ Combine with `--list` to match optional pattern(s).
@@ -314,6 +322,18 @@ $ git branch -D test <2>
<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.
+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.
diff --git a/builtin/branch.c b/builtin/branch.c
index 1be7272..30906d4 100644
--- a/builtin/branch.c
+++ b/builtin/branch.c
@@ -810,7 +810,8 @@ int cmd_branch(int argc, const char **argv, const char *prefix)
} else if (argc > 0 && argc <= 2) {
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>?"));
die(_("the '--set-upstream' option is no longer supported. Please use '--track' or '--set-upstream-to' instead."));