Git
简体中文 ▾ Topics ▾ Latest version ▾ git-branch last updated in 2.37.1

名称

git-branch - 列出、创建或删除分支

概述

git branch [--color[=<when>] |--no-color] [--show-current]
	[-v [--abbrev=<n> |--no-abbrev] ]
	[--column[=<options>] | --no-column][--sort=<key>]
	[--合并 [<commit>]][--no-merged [<commit>]]。
	[--包含[<commit>]][--no-contains [<commit>]] [--contains [<commit>]]
	[--points-at <object>] [--format=<format>]。
	[(-r | --remotes) | (-a | --all)
	[--列表] [<pattern>…​]
git branch [--track |-no-track] [-f] <branchname> [<start-point>]。
git branch (-set-upstream-to=<upstream> | -u <upstream>) [<branchname>]
git branch --unset-upstream [<branchname>]
git branch (-m | -M) [<oldbranch>] <newbranch>
git branch (-c | -C) [<oldbranch>] <newbranch>
git branch (-d | -D) [-r] <branchname>…​
git branch --edit-description [<branchname>])

描述

如果给了`--list`,或者没有非选项参数,现有的分支将被列出;当前的分支将以绿色突出显示,并标有星号。 在链接的工作树中检查出来的任何分支将以青色突出显示,并标有加号。选项`-r`导致远程跟踪的分支被列出,选项`-a`显示本地和远程分支。

如果给出了`<pattern>`,它被用作shell通配符,将输出限制在匹配的分支上。如果给出多个模式,如果一个分支与任何模式相匹配,就会显示出来。

注意,当提供"<pattern>"时,必须使用"--list";否则命令可能被解释为创建分支。

使用 --contains 时,只显示包含指定提交的分支(换句话说,尖端提交是指定提交的后裔的分支),--no-contains 会反过来。如果使用 --merged,则只列出被合并到指定提交的分支(即其顶端提交可以从指定提交处到达的分支)。 如果使用"--no-merged",则只列出未被合并到指定提交的分支。 如果缺少<commit>参数,则默认为`HEAD`(即当前分支的顶端)。

该命令的第二种形式是创建一个名为<branchname>的新分支头,该分支头指向当前的`HEAD`,如果给定的话,则指向<start-point>。作为一种特殊情况,对于<start-point>,你可以使用`"A…​B "作为`A`和`B`的合并基础的快捷方式,如果正好有一个合并基础。你最多可以省略`A`和`B`中的一个,在这种情况下,它默认为`HEAD`。

注意,这将创建新的分支,但不会将工作树切换到它;使用 "git switch <newbranch>"来切换到新的分支。

当一个本地分支从远程跟踪的分支开始时,Git 会设置该分支(特别是 branch.<name>.remotebranch.<name>.merge 配置项),以便 "git pull "能适当地从远程跟踪的分支合并。这种行为可以通过全局的 branch.autoSetupMerge 配置标志来改变。该设置可以通过使用`--track`和`--no-track`选项来覆盖,并在之后使用`git branch --set-upstream-to`来改变。

使用`-m`或`-M`选项,<oldbranch>将被重命名为<newbranch>。 如果 <oldbranch> 有相应的 reflog,它将被重命名以匹配 <newbranch>,并创建一个 reflog 条目以记住分支重命名。如果 <newbranch> 存在,必须使用 -M 来强制重命名。

-c`和-C`选项的语义与`-m`和`-M`完全相同,只不过不是对分支进行重命名,而是将其连同其配置和日志一起复制到一个新的名称。

使用`-d`或`-D`选项,`<branchname>`将被删除。 你可以指定一个以上的分支进行删除。 如果该分支目前有一个reflog,那么reflog也将被删除。

使用 -r-d 来删除远程跟踪的分支。注意,只有当远程分支不再存在于远程仓库或 "git fetch "被配置为不再获取它们时,删除远程跟踪分支才有意义。参见 git-remote[1] 的 "prune "子命令,它可以清理所有过时的远程跟踪分支。

选项

-d
--delete

删除一个分支。该分支必须完全合并在其上游分支中,如果没有用`--track`或`--set-upstream-to`设置的上游分支,则必须在`HEAD`中。

-D

`--delete --force`的快捷方式。

--create-reflog

创建该分支的 reflog。 这将激活对该分支参考文献所做的所有修改的记录,使其能够使用基于日期的sha1表达式,如"<branchname>@{yesterday}"。 请注意,在非空白仓库中, reflogs通常由`core.logAllRefUpdates`配置选项默认启用。 否定的形式`--no-create-reflog`只覆盖先前的`--create-reflog`,但目前并不否定`core.logAllRefUpdates`的设置。

-f
--force

Reset <branchname> to <startpoint>, even if <branchname> exists already. Without -f, git branch refuses to change an existing branch. In combination with -d (or --delete), allow deleting the branch irrespective of its merged status, or whether it even points to a valid commit. In combination with -m (or --move), allow renaming the branch even if the new branch name already exists, the same applies for -c (or --copy).

-m
--move

Move/rename a branch, together with its config and reflog.

-M

`--move --force`的快捷方式。

-c
--copy

Copy a branch, together with its config and reflog.

-C

`--copy --force`的快捷方式。

--color[=<when>]

给分支着色,以突出当前、本地和远程跟踪的分支。 该值必须是始终(默认)、从不或自动。

--no-color

关闭分支的颜色,即使在配置文件中默认为彩色输出。 与`--color=never`相同。

-i
--ignore-case

排序和过滤分支是不分大小写的。

--column[=<选项>]
--no-column

在列中显示分支列表。选项语法见配置变量`column.branch`。--column`和--no-column`没有选项,分别相当于’always’和’never'。

这个选项只适用于非粗话模式。

-r
--remotes

列出或删除(如果与-d一起使用)远程跟踪的分支。 与`--list`结合使用,以匹配可选的模式(s)。

-a
--all

列出远程跟踪的分支和本地分支。 与`--list`组合,以匹配可选的模式。

-l
--list

列出分支。 使用可选的"<pattern>…​",例如 "git branch --list maint-*",只列出符合该模式的分支。

--show-current

打印当前分支的名称。在分离的HEAD状态下,不打印任何东西。

-v
-vv
--verbose

当在列表模式下,显示每个头的sha1和提交主题行,以及与上游分支的关系(如果有的话)。如果给了两次,也会打印链接的工作树的路径(如果有的话)和上游分支的名称(也见 git remote show <remote>)。 请注意,当前工作树的HEAD不会打印其路径(它总是你的当前目录)。

-q
--quiet

在创建或删除一个分支时更加安静,抑制非错误信息。

--abbrev=<n>

在显示提交对象名称的冗长列表中,显示至少有'<n>'个六位数的最短前缀,以唯一地指代该对象。 默认值是7,可以通过`core.abbrev`配置选项覆盖。

--no-abbrev

在输出列表中显示完整的sha1,而不是缩写它们。

-t
--track

在创建新分支时,设置`branch.<name>.remote`和`branch.<name>.merge`配置项,将起始点分支标记为新分支的 "上游"。这个配置将告诉git在`git status`和`git branch -v`中显示这两个分支之间的关系。此外,它还指示`git pull`在新分支被检出时,不带参数地从上游提取。

当起点是一个远程跟踪的分支时,这种行为是默认的。 如果你想让 "git switch"、"git checkout "和 "git branch "总是表现得像"--no-track "一样,就把 branch.autoSetupMerge 配置变量设为 "false"。如果你想在起始点是本地或远程跟踪的分支时有这种行为,则将其设置为`always`。

--no-track

不要设置 "上游 "配置,即使 branch.autoSetupMerge 配置变量为 true。

--set-upstream

由于这个选项的语法混乱,不再支持。 请使用`--track`或`--set-upstream-to`代替。

-u <上行>
--set-upstream-to=<upstream>

设置<branchname>的跟踪信息,使<upstream>被视为<branchname>的上游分支。如果没有指定<branchname>,则默认为当前分支。

--unset-upstream

删除<branchname>的上游信息。如果没有指定分支,则默认为当前分支。

--edit-description

打开一个编辑器,编辑文本,解释该分支的用途,以便被其他各种命令(如`format-patch`、request-pull`和`merge(如果启用))使用。可以使用多行解释。

--contains [<commit>]

只列出包含指定提交的分支(如果没有指定则为HEAD)。意味着 --list

--no-contains [<commit>]

只列出不包含指定提交的分支(如果不指定则为HEAD)。意味着 --list

--merged [<commit>]

只列出从指定的提交(如果没有指定,则为HEAD)可以到达的分支的提示。意味着 --list

--no-merged [<commit>]

只列出从指定的提交(如果没有指定,则为HEAD)中无法到达的分支。意味着 --list

<branchname>

要创建或删除的分支的名称。 新的分支名必须通过 git-check-ref-format[1] 定义的所有检查。 其中一些检查可能会限制分支名称中允许的字符。

<起始点

新的分支头将指向这个提交。 它可以是一个分支名,一个提交号,或者一个标签。 如果省略此选项,将使用当前的HEAD来代替。

<oldbranch>

要重命名的现有分支的名称。

<newbranch>

现有分支的新名称。与<branchname>的限制相同。

--排序=<键>

根据给定的键进行排序。前缀"-"表示按照数值的降序排序。你可以多次使用—​sort=<key>选项,在这种情况下,最后一个键成为主键。支持的键与`git for-each-ref`中的键相同。排序顺序默认为`branch.sort`变量的配置值(如果存在),或者基于完整的 refname(包括 refs/... 前缀)进行排序。这将首先列出分离的 HEAD(如果存在),然后是本地分支,最后是远程跟踪分支。参见 git-config[1]

--points-at <object>

只列出给定对象的分支。

--format <format>

一个字符串,从正在显示的分支参考文献和它所指向的对象中插值`%(fieldname)'。 其格式与git-for-each-ref[1]的格式相同。

配置

pager.branch`只在列出分支时被尊重,即使用或暗示使用--list`时。默认情况是使用 pager。 参见 git-config[1]

EXAMPLES

从一个已知的标签开始开发
$ git clone git://git.kernel.org/pub/scm/.../linux-2.6 my2.6
$ cd my2.6
$ git branch my2.6.14 v2.6.14 <1>.
$ git switch my2.6.14
  1. 这一步和下一步可以用 "checkout -b my2.6.14 v2.6.14 "合并为一个步骤。

删除一个不需要的分支
$ git clone git://git.kernel.org/.../git.git my.git
$ cd my.git
$ git branch -d -r origin/todo origin/html origin/man   (1)
$ git branch -D test                                    (2)
  1. 删除远程跟踪的分支 "todo"、"html "和 "man"。下一次的 "fetch "或 "pull "会再次创建它们,除非你配置它们不这样做。 参见 git-fetch[1]

  2. 删除 "测试 "分支,即使 "主 "分支(或当前签出的任何一个分支)没有测试分支的所有提交。

从一个特定的远端列出分支
$ git branch -r -l '<remote>/<pattern>'                 (1)
$ git for-each-ref 'refs/remotes/<remote>/<pattern>'    (2)
  1. 使用`-a`会将<remote>与任何你碰巧以相同的<remote>模式为前缀的本地分支混淆。

  2. `for-each-ref`可以接受一系列的选项。参见 git-for-each-ref[1]

图案通常需要引证。

NOTES

如果你正在创建一个你想立即切换到的分支,使用 "git switch "命令及其`-c`选项,用一条命令做同样的事情,会更容易。

选项`--包含`、--不包含--合并`和--不合并`有四个相关但不同的目的。

  • `--contains <commit>`用于查找所有在<commit>被重新编译或修改时需要特别关注的分支,因为这些分支包含指定的<commit>。

  • `--no-contains <commit>`是其反义词,即不包含指定<commit>的分支。

  • `--merged`用于查找所有可以安全删除的分支,因为这些分支被HEAD完全包含。

  • `--no-merged`是用来寻找可以合并到HEAD的候选分支,因为这些分支没有被HEAD完全包含。

当组合多个"---包含 "和"---不包含 "过滤器时,只显示至少包含一个"---包含 "的提交,并且不包含"---不包含 "的提交的参考。

当结合多个 "合并 "和 "未合并 "过滤器时,只显示至少有一个 "合并 "提交和没有 "未合并 "提交的引用。

GIT

Part of the git[1] suite

scroll-to-top