From: Junio C Hamano Date: Tue, 9 Jul 2019 22:25:34 +0000 (-0700) Subject: Merge branch 'po/doc-branch' X-Git-Tag: v2.23.0-rc0~94 X-Git-Url: https://git.lorimer.id.au/gitweb.git/diff_plain/ecf55ae4f0f73a9759eb58e01cfcc6758acc07c2?hp=-c Merge branch 'po/doc-branch' Doc update. * po/doc-branch: doc branch: provide examples for listing remote tracking branches --- ecf55ae4f0f73a9759eb58e01cfcc6758acc07c2 diff --combined Documentation/git-branch.txt index 7c8fa3b64f,c57f6a15c6..16e14c6282 --- a/Documentation/git-branch.txt +++ b/Documentation/git-branch.txt @@@ -8,12 -8,14 +8,14 @@@ 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] ++'git branch' [--color[=] | --no-color] [--show-current] + [-v [--abbrev= | --no-abbrev]] [--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 [] @@@ -26,15 -28,17 +28,19 @@@ 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, +branches are listed; the current branch will be highlighted in green and +marked with an asterisk. Any branches checked out in linked worktrees will +be highlighted in cyan and marked with a plus sign. 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 @@@ -47,11 -51,7 +53,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 @@@ -155,10 -155,12 +161,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:: @@@ -166,20 -168,14 +174,20 @@@ 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:: When in list mode, show sha1 and commit subject line for each head, along with relationship to upstream branch (if any). If given twice, print - the name of the upstream branch, as well (see also `git remote - show `). + the path of the linked worktree (if any) and the name of the upstream + branch, as well (see also `git remote show `). Note that the + current worktree's HEAD will not have its path printed (it will always + be your current directory). -q:: --quiet:: @@@ -326,6 -322,18 +334,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 2cb45e42e1,30906d4526..2ef214632f --- a/builtin/branch.c +++ b/builtin/branch.c @@@ -47,7 -47,6 +47,7 @@@ static char branch_colors[][COLOR_MAXLE GIT_COLOR_NORMAL, /* LOCAL */ GIT_COLOR_GREEN, /* CURRENT */ GIT_COLOR_BLUE, /* UPSTREAM */ + GIT_COLOR_CYAN, /* WORKTREE */ }; enum color_branch { BRANCH_COLOR_RESET = 0, @@@ -55,8 -54,7 +55,8 @@@ BRANCH_COLOR_REMOTE = 2, BRANCH_COLOR_LOCAL = 3, BRANCH_COLOR_CURRENT = 4, - BRANCH_COLOR_UPSTREAM = 5 + BRANCH_COLOR_UPSTREAM = 5, + BRANCH_COLOR_WORKTREE = 6 }; static const char *color_branch_slots[] = { @@@ -66,7 -64,6 +66,7 @@@ [BRANCH_COLOR_LOCAL] = "local", [BRANCH_COLOR_CURRENT] = "current", [BRANCH_COLOR_UPSTREAM] = "upstream", + [BRANCH_COLOR_WORKTREE] = "worktree", }; static struct string_list output = STRING_LIST_INIT_DUP; @@@ -345,10 -342,9 +345,10 @@@ static char *build_format(struct ref_fi struct strbuf local = STRBUF_INIT; struct strbuf remote = STRBUF_INIT; - strbuf_addf(&local, "%%(if)%%(HEAD)%%(then)* %s%%(else) %s%%(end)", - branch_get_color(BRANCH_COLOR_CURRENT), - branch_get_color(BRANCH_COLOR_LOCAL)); + strbuf_addf(&local, "%%(if)%%(HEAD)%%(then)* %s%%(else)%%(if)%%(worktreepath)%%(then)+ %s%%(else) %s%%(end)%%(end)", + branch_get_color(BRANCH_COLOR_CURRENT), + branch_get_color(BRANCH_COLOR_WORKTREE), + branch_get_color(BRANCH_COLOR_LOCAL)); strbuf_addf(&remote, " %s", branch_get_color(BRANCH_COLOR_REMOTE)); @@@ -367,13 -363,9 +367,13 @@@ strbuf_addf(&local, " %s ", obname.buf); if (filter->verbose > 1) + { + strbuf_addf(&local, "%%(if:notequals=*)%%(HEAD)%%(then)%%(if)%%(worktreepath)%%(then)(%s%%(worktreepath)%s) %%(end)%%(end)", + branch_get_color(BRANCH_COLOR_WORKTREE), branch_get_color(BRANCH_COLOR_RESET)); strbuf_addf(&local, "%%(if)%%(upstream)%%(then)[%s%%(upstream:short)%s%%(if)%%(upstream:track)" "%%(then): %%(upstream:track,nobracket)%%(end)] %%(end)%%(contents:subject)", branch_get_color(BRANCH_COLOR_UPSTREAM), branch_get_color(BRANCH_COLOR_RESET)); + } else strbuf_addf(&local, "%%(if)%%(upstream:track)%%(then)%%(upstream:track) %%(end)%%(contents:subject)"); @@@ -451,21 -443,6 +451,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); @@@ -604,7 -581,6 +604,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; @@@ -644,7 -620,6 +644,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")), @@@ -652,7 -627,8 +652,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 @@@ -686,15 -662,14 +686,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); @@@ -722,9 -697,6 +722,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) @@@ -838,7 -810,8 +838,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."));