From: Junio C Hamano Date: Mon, 29 Jul 2019 19:38:16 +0000 (-0700) Subject: Merge branch 'po/doc-branch' into maint X-Git-Tag: v2.23.0-rc0~1^2~21 X-Git-Url: https://git.lorimer.id.au/gitweb.git/diff_plain/0c47e8ddf5e6584fe8baf8d25b2bcc4ca4c9cb5d?ds=inline;hp=-c Merge branch 'po/doc-branch' into maint Doc update. * po/doc-branch: doc branch: provide examples for listing remote tracking branches --- 0c47e8ddf5e6584fe8baf8d25b2bcc4ca4c9cb5d diff --combined Documentation/git-branch.txt index 6ebd512b4f,c57f6a15c6..d9325e2145 --- a/Documentation/git-branch.txt +++ b/Documentation/git-branch.txt @@@ -8,12 -8,14 +8,15 @@@ git-branch - List, create, or delete br SYNOPSIS -------- [verse] - 'git branch' [--color[=] | --no-color] [-r | -a] - [--list] [--show-current] [-v [--abbrev= | --no-abbrev]] + 'git branch' [--color[=] | --no-color] + [-v [--abbrev= | --no-abbrev]] ++ [--show-current] [--column[=] | --no-column] [--sort=] [(--merged | --no-merged) []] [--contains []] - [--points-at ] [--format=] [...] + [--points-at ] [--format=] + [(-r | --remotes) | (-a | --all)] + [--list] [...] 'git branch' [--track | --no-track] [-f] [] 'git branch' (--set-upstream-to= | -u ) [] 'git branch' --unset-upstream [] @@@ -28,11 -30,15 +31,15 @@@ DESCRIPTIO 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 `` + and option `-a` shows both local and remote branches. + + If a `` 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 - ``, you must use `--list`; otherwise the command is interpreted + it matches any of the patterns. + + Note that when providing a + ``, you must use `--list`; otherwise the command may be interpreted as branch creation. With `--contains`, shows only the branches that contain the named commit @@@ -45,11 -51,7 +52,11 @@@ argument is missing it defaults to `HEA branch). The command's second form creates a new branch head named -which points to the current `HEAD`, or if given. +which points to the current `HEAD`, or if given. As a +special case, for , you may use `"A...B"` as a shortcut for +the merge base of `A` and `B` if there is exactly one merge base. You +can leave out at most one of `A` and `B`, in which case it defaults to +`HEAD`. Note that this will create the new branch, but it will not switch the working tree to it; use "git checkout " to switch to the @@@ -153,10 -155,12 +160,12 @@@ This option is only applicable in non-v -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:: @@@ -164,10 -168,6 +173,10 @@@ branch --list 'maint-*'`, list only the branches that match the pattern(s). +--show-current:: + Print the name of the current branch. In detached HEAD state, + nothing is printed. + -v:: -vv:: --verbose:: @@@ -322,6 -322,18 +331,18 @@@ $ git branch -D tes <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 '/' <1> + $ git for-each-ref 'refs/remotes//' <2> + ------------ + + + <1> Using `-a` would conflate with any local branches you happen to + have been prefixed with the same 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 --combined builtin/branch.c index d4359b33ac,30906d4526..8e243cf8c2 --- a/builtin/branch.c +++ b/builtin/branch.c @@@ -443,21 -443,6 +443,21 @@@ static void print_ref_list(struct ref_f free(to_free); } +static void print_current_branch_name(void) +{ + int flags; + const char *refname = resolve_ref_unsafe("HEAD", 0, NULL, &flags); + const char *shortname; + if (!refname) + die(_("could not resolve HEAD")); + else if (!(flags & REF_ISSYMREF)) + return; + else if (skip_prefix(refname, "refs/heads/", &shortname)) + puts(shortname); + else + die(_("HEAD (%s) points outside of refs/heads/"), refname); +} + static void reject_rebase_or_bisect_branch(const char *target) { struct worktree **worktrees = get_worktrees(0); @@@ -596,7 -581,6 +596,7 @@@ static int edit_branch_description(cons int cmd_branch(int argc, const char **argv, const char *prefix) { int delete = 0, rename = 0, copy = 0, force = 0, list = 0; + int show_current = 0; int reflog = 0, edit_description = 0; int quiet = 0, unset_upstream = 0; const char *new_upstream = NULL; @@@ -636,7 -620,6 +636,7 @@@ OPT_BIT('c', "copy", ©, N_("copy a branch and its reflog"), 1), OPT_BIT('C', NULL, ©, N_("copy a branch, even if target exists"), 2), OPT_BOOL('l', "list", &list, N_("list branch names")), + OPT_BOOL(0, "show-current", &show_current, N_("show current branch name")), OPT_BOOL(0, "create-reflog", &reflog, N_("create the branch's reflog")), OPT_BOOL(0, "edit-description", &edit_description, N_("edit the description for the branch")), @@@ -644,7 -627,8 +644,7 @@@ OPT_MERGED(&filter, N_("print only branches that are merged")), OPT_NO_MERGED(&filter, N_("print only branches that are not merged")), OPT_COLUMN(0, "column", &colopts, N_("list branches in columns")), - OPT_CALLBACK(0 , "sort", sorting_tail, N_("key"), - N_("field name to sort on"), &parse_opt_ref_sorting), + OPT_REF_SORT(sorting_tail), { OPTION_CALLBACK, 0, "points-at", &filter.points_at, N_("object"), N_("print only branches of the object"), 0, parse_opt_object_name @@@ -678,15 -662,14 +678,15 @@@ argc = parse_options(argc, argv, prefix, options, builtin_branch_usage, 0); - if (!delete && !rename && !copy && !edit_description && !new_upstream && !unset_upstream && argc == 0) + if (!delete && !rename && !copy && !edit_description && !new_upstream && + !show_current && !unset_upstream && argc == 0) list = 1; if (filter.with_commit || filter.merge != REF_FILTER_MERGED_NONE || filter.points_at.nr || filter.no_commit) list = 1; - if (!!delete + !!rename + !!copy + !!new_upstream + + if (!!delete + !!rename + !!copy + !!new_upstream + !!show_current + list + unset_upstream > 1) usage_with_options(builtin_branch_usage, options); @@@ -714,9 -697,6 +714,9 @@@ if (!argc) die(_("branch name required")); return delete_branches(argc, argv, delete > 1, filter.kind, quiet); + } else if (show_current) { + print_current_branch_name(); + return 0; } else if (list) { /* git branch --local also shows HEAD when it is detached */ if ((filter.kind & FILTER_REFS_BRANCHES) && filter.detached) @@@ -830,7 -810,8 +830,8 @@@ 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 ?")); if (track == BRANCH_TRACK_OVERRIDE) die(_("the '--set-upstream' option is no longer supported. Please use '--track' or '--set-upstream-to' instead."));