Git
简体中文 ▾ Topics ▾ Latest version ▾ git-branch last updated in 2.34.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>.remote 和 branch.<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完全包含。

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

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

SEE ALSO

git-check-ref-format[1], git-fetch[1], git-remote[1], ‘`了解历史：什么是分支？’ 在 Git User’s Manual。

GIT

Part of the git[1] suite

scroll-to-top