| Message ID | 20190528231605.10108-1-philipoakley@iee.org (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
| Series | [RFC/PATCH,v2] doc branch: provide examples for listing remote tracking branches | expand |
Philip Oakley <philipoakley@iee.org> writes: > 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> > --- > > in response to > <2ea35ad4-4b33-0ece-4de4-b2e92a100d9a@iee.org> > thread: https://public-inbox.org/git/?q=%3CCACsJy8CwY8gzeWa9kNRX3ecez1JGiQiaOknbAoU7S%2BhiXBoUGQ%40mail.gmail.com%3E > > to: Git Mailing List <git@vger.kernel.org> > cc: Duy Nguyen <pclouds@gmail.com> > cc: Ævar Arnfjörð Bjarmason <avarab@gmail.com> > cc: Junio C Hamano <gitster@pobox.com> This looks reasonable to me---is it ready to go even with its RFC prefix?
Hi Junio, On 10/06/2019 18:57, Junio C Hamano wrote: > Philip Oakley <philipoakley@iee.org> writes: > >> 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> >> --- >> >> in response to >> <2ea35ad4-4b33-0ece-4de4-b2e92a100d9a@iee.org> >> thread: https://public-inbox.org/git/?q=%3CCACsJy8CwY8gzeWa9kNRX3ecez1JGiQiaOknbAoU7S%2BhiXBoUGQ%40mail.gmail.com%3E >> >> to: Git Mailing List <git@vger.kernel.org> >> cc: Duy Nguyen <pclouds@gmail.com> >> cc: Ævar Arnfjörð Bjarmason <avarab@gmail.com> >> cc: Junio C Hamano <gitster@pobox.com> > This looks reasonable to me---is it ready to go even with its RFC prefix? Yes; the RFC was only in regard of the die() message change as it touches real code;-) Following the post, Stolee's coverage report, it was noted that the die() wasn't actually tested, so I sent a quick follow-up of a potential test https://public-inbox.org/git/f28dd5b1-fda8-cf51-5582-067a7d2c2472@iee.org/ which is a proper RFC... I did not attempt to see if any other dies()'s were untested, just copied one that was.. Philip (currently travelling)
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 SYNOPSIS -------- [verse] -'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. -r:: --remotes:: List or delete (if used with -d) the remote-tracking branches. + Combine with `--list` to match the optional pattern(s). -a:: --all:: List both remote-tracking branches and local branches. + Combine with `--list` to match optional pattern(s). -l:: --list:: @@ -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. NOTES ----- 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) strbuf_release(&buf); } 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."));
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> --- in response to <2ea35ad4-4b33-0ece-4de4-b2e92a100d9a@iee.org> thread: https://public-inbox.org/git/?q=%3CCACsJy8CwY8gzeWa9kNRX3ecez1JGiQiaOknbAoU7S%2BhiXBoUGQ%40mail.gmail.com%3E to: Git Mailing List <git@vger.kernel.org> cc: Duy Nguyen <pclouds@gmail.com> cc: Ævar Arnfjörð Bjarmason <avarab@gmail.com> cc: Junio C Hamano <gitster@pobox.com> Documentation/git-branch.txt | 32 ++++++++++++++++++++++++++------ builtin/branch.c | 3 ++- 2 files changed, 28 insertions(+), 7 deletions(-)