Git

git-branch last updated in 2.44.0

名称

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

概述

git branch [--color[=<when>] | --no-color] [--show-current]
	[-v [--abbrev=<n> | --no-abbrev]]
	[--column[=<options>] | --no-column] [--sort=<key>]
	[--merged [<commit>]] [--no-merged [<commit>]]
	[--contains [<commit>]] [--no-contains [<commit>]]
	[--points-at <object>] [--format=<format>]
	[(-r | --remotes) | (-a | --all)]
	[--list] [<pattern>…]
git branch [--track[=(direct|inherit)] | --no-track] [-f]
	[--recurse-submodules] <分支名> [<起始点>]
git branch (--set-upstream-to=<上游> | -u <上游>) [<分支名>]
git branch --unset-upstream [<分支名>]
git branch (-m | -M) [<旧分支>] <新分支>
git branch (-c | -C) [<旧分支>] <新分支>
git branch (-d | -D) [-r] <分支名>…
git branch --edit-description [<分支名>]

描述

如果给了`--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: 将 <分支名> 重置为 <起始点>，即使 <分支名> 已经存在。如果没有 -f，git branch 会拒绝更改现有分支。与 -d（或 --delete）结合使用时，允许删除分支，而不管其合并状态如何，也不管它是否指向一个有效的提交。结合 -m（或 --move），允许重命名分支，即使新的分支名称已经存在，这同样适用于 -c（或 --copy）。

请注意，"git branch -f <branchname> [<start-point>]"命令，即使添加"-f"选项，该命令也会拒绝改变一个在链接到同一仓库的另一个工作树中被检查出来的现有分支`<branchname>`。
-m
--move: 移动/重命名分支及其配置和引用日志。
-M: `--move --force`的快捷方式。
-c
--copy: 复制分支及其配置和引用日志。
-C: `--copy --force`的快捷方式。
--color[=<when>]: 给分支着色，以突出当前、本地和远程跟踪的分支。该值必须是始终（默认）、从不或自动。
--no-color: 关闭分支的颜色，即使在配置文件中默认为彩色输出。与`--color=never`相同。
-i
--ignore-case: 排序和过滤分支是不分大小写的。
--omit-empty: 在格式化的引用后不打印换行，因为格式化的引用会扩展为空字符串。
--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[=(direct|inherit)]: 在创建一个新分支时，设置 branch.<name>.remote 和 branch.<name>.merge 配置项来为新分支设置“上游”追踪。这个配置将告诉 git 在 git status 和 git branch -v 中显示这两个分支之间的关系（译者注：应该是 git branch -vv 命令而不是 git branch -v 命令，这样才会显示某一分支的上游）。此外，它还指示了在该新分支上运行不带参数的 git pull 命令时，将直接从上游拉取。

想要选择确切的上游分支可以使用可选参数：-t、--track 或 --track=direct，这些参数均表示使用 <start-point> 分支本身作为上游分支；--track=inherit 表示继承 <start-point> 分支的上游配置。

branch.autoSetupMerge配置变量指定了当既不指定`--track`也不指定`--no-track`时，git switch、`git checkout`和`git branch`应如何运行：

默认选项 true，在起点是远程跟踪分支的情况下，就像给了 --track=direct。 false 的行为就像给了 --no-track 一样。always`的行为就像给了 `--track=direct 一样。继承(inherit)的行为就像给了 --track=inherit 一样。simple`的行为就像给了--track=direct`一样，只有当起点是远程跟踪的分支，并且新的分支与远程分支有相同的名字时，才会有这种行为。

有关如何使用 branch.<名称>.remote 和 branch.<名称>.merge 选项的更多讨论，请参见 git-pull[1] 和 git-config[1]。
--no-track: 不要设置 “上游仓库” 配置，即使 branch.autoSetupMerge 配置变量为 true。
--recurse-submodules: 这个选项是实验性的！！！如果 submodule.propagateBranches 被启用，会导致当前命令递归到子模块。参见 git-config[1] 中的 submodule.propagateBranches。目前，只支持创建分支。

当在分支创建中使用时，一个新的分支<branchname>将在父项目和父项目的<start-point>中的所有子模块中创建。在子模块中，该分支将指向超级项目的<start-point>中的子模块提交，但该分支的跟踪信息将根据子模块的分支和远程来设置，例如`git branch --recurse-submodules topic origin/main`将创建一个子模块分支 "topic"，指向父项目的 "origin/main "中的子模块提交，但跟踪子模块的 "origin/main"。
--set-upstream: 由于这个选项的语法混乱，不再支持。请使用`--track`或`--set-upstream-to`代替。
-u <上行>
--set-upstream-to=<上游仓库>: 设置<branchname>的跟踪信息，使<upstream>被视为<branchname>的上游分支。如果没有指定<branchname>，则默认为当前分支。
--unset-upstream: 删除<branchname>的上游信息。如果没有指定分支，则默认为当前分支。
--edit-description: 打开一个编辑器，编辑文本，解释该分支的用途，以便被其他各种命令（如`format-patch`、request-pull`和`merge（如果启用））使用。可以使用多行解释。
--contains [<提交>]: 只列出包含指定提交的分支（如果没有指定则为HEAD）。意味着 --list。
--no-contains [<提交>]: 只列出不包含指定提交的分支（如果不指定则为HEAD）。意味着 --list。
--merged [<提交>]: 只列出从指定的提交（如果没有指定，则为HEAD）可以到达的分支的提示。意味着 --list。
--no-merged [<提交>]: 只列出从指定的提交（如果没有指定，则为HEAD）中无法到达的分支。意味着 --list。
<branchname>: 要创建或删除的分支的名称。新的分支名必须通过 git-check-ref-format[1] 定义的所有检查。其中一些检查可能会限制分支名称中允许的字符。
<start-point>: 新的分支头将指向这个提交。它可以是一个分支名，一个提交号，或者一个标签。如果省略此选项，将使用当前的HEAD来代替。
<旧分支>: 新的分支头将指向这个提交。它可以是一个分支名，一个提交号，或者一个标签。如果省略此选项，将使用当前的HEAD来代替。
<新分支>: 现有分支的新名称。与<branchname>的限制相同。
--sort=<键>: 根据给定的键进行排序。前缀"-"表示按照数值的降序排序。你可以多次使用 --sort=<键> 选项，在这种情况下，最后一个键成为主键。支持的键与 git for-each-ref 中的键相同。排序顺序默认为 branch.sort 变量的配置值（如果存在），或者基于完整的引用名（包括 refs/... 前缀）进行排序。这将首先列出分离的 HEAD（如果存在），然后是本地分支，最后是远程跟踪分支。参见 git-config[1]。
--points-at <对象>: 只列出给定对象的分支。
--format <格式>: 一个字符串，从正在显示的分支参考文献和它所指向的对象中插值`%(fieldname)'。其格式与git-for-each-ref[1]的格式相同。

配置

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

Warning

Missing zh_HANS-CN/includes/cmd-config-section-rest.txt

See original version for this content.

Warning

Missing zh_HANS-CN/config/branch.txt

See original version for this content.

实例

从一个已知的标签开始开发

$ 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

这一步和下一步可以用 "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)

删除远程跟踪的分支 "todo"、"html "和 "man"。下一次的 "fetch "或 "pull "会再次创建它们，除非你配置它们不这样做。参见 git-fetch[1]。
删除 "测试 "分支，即使 "主 "分支（或当前签出的任何一个分支）没有测试分支的所有提交。

从一个特定的远端列出分支

$ git branch -r -l '<远程仓库>/<模式>'                 (1)
$ git for-each-ref 'refs/remotes/<远程仓库>/<模式>'    (2)

使用`-a`会将<remote>与任何你碰巧以相同的<remote>模式为前缀的本地分支混淆。
for-each-ref 可以接受一系列的选项。参见 git-for-each-ref[1]

图案通常需要引证。

注释

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

选项 --contains, --no-contains, --merged 和 --no-merged 分别用于执行四个相关但不同的功能：

`--contains <commit>`用于查找所有在<commit>被重新编译或修改时需要特别关注的分支，因为这些分支包含指定的<commit>。
`--no-contains <commit>`是其反义词，即不包含指定<commit>的分支。
`--merged`用于查找所有可以安全删除的分支，因为这些分支被HEAD完全包含。
`--no-merged`是用来寻找可以合并到HEAD的候选分支，因为这些分支没有被HEAD完全包含。

当组合多个 --contains 和 --no-contains 过滤器时，只显示至少包含一个 --contains 的提交，并且不包含 --no-contains 的提交引用。

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

参见

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

属于 git[1] 文档

Setup and Config

Getting and Creating Projects

Basic Snapshotting

Branching and Merging

Sharing and Updating Projects

Inspection and Comparison

Patching

Debugging

Email

External Systems

Server Admin

Guides

Administration

Plumbing Commands

名称

概述

描述

选项

配置

实例

注释

参见

GIT