mailing list mirror (one of many)
 help / color / mirror / code / Atom feed
From: Philip Oakley <>
To: GitList <>
Cc: "Duy Nguyen" <>,
	"Ævar Arnfjörð Bjarmason" <>,
	"Junio C Hamano" <>
Subject: [RFC/PATCH v2] doc branch: provide examples for listing remote tracking branches
Date: Wed, 29 May 2019 00:16:05 +0100	[thread overview]
Message-ID: <> (raw)
In-Reply-To: <>

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

in response to 

to: Git Mailing List <>
cc: Duy Nguyen <>
cc: Ævar Arnfjörð Bjarmason <>
cc: Junio C Hamano <>

 Documentation/git-branch.txt | 32 ++++++++++++++++++++++++++------
 builtin/branch.c             |  3 ++-
 2 files changed, 28 insertions(+), 7 deletions(-)

diff --git a/Documentation/git-branch.txt b/Documentation/git-branch.txt
index 3bd83a7cbd..c57f6a15c6 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 1be727209b..30906d4526 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>?"));
 		if (track == BRANCH_TRACK_OVERRIDE)
 			die(_("the '--set-upstream' option is no longer supported. Please use '--track' or '--set-upstream-to' instead."));

  reply	other threads:[~2019-05-28 23:16 UTC|newest]

Thread overview: 16+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2019-05-18 15:16 Command to list <pattern> Branches on a specific Remote (i.e. select from rtb's) Philip Oakley
2019-05-18 18:37 ` Ævar Arnfjörð Bjarmason
2019-05-18 19:44   ` Philip Oakley
2019-05-19  3:07     ` Duy Nguyen
2019-05-19  9:49       ` Philip Oakley
2019-05-28 12:13       ` [PATCH] doc branch: provide examples for listing remote tracking branches Philip Oakley
2019-05-28 13:58         ` Junio C Hamano
2019-05-28 14:17           ` Philip Oakley
2019-05-28 14:51             ` Philip Oakley
2019-05-28 15:51               ` Junio C Hamano
2019-05-28 16:17                 ` Philip Oakley
2019-05-28 23:16                   ` Philip Oakley [this message]
2019-06-10 17:57                     ` [RFC/PATCH v2] " Junio C Hamano
2019-06-14 21:00                       ` Philip Oakley
2019-05-19  3:05   ` Command to list <pattern> Branches on a specific Remote (i.e. select from rtb's) Duy Nguyen
2019-05-28 13:57   ` Junio C Hamano

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:

  List information:

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \ \ \ \ \ \ \

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
Code repositories for project(s) associated with this public inbox

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).