简体中文 ▾ 主题 ▾ 最新版本 ▾ git-branch 上次更新于 2.50.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] <branch-name> [<start-point>]
git branch (--set-upstream-to=<upstream>|-u <upstream>) [<branch-name>]
git branch --unset-upstream [<branch-name>]
git branch (-m|-M) [<old-branch>] <new-branch>
git branch (-c|-C) [<old-branch>] <new-branch>
git branch (-d|-D) [-r] <branch-name>…​
git branch --edit-description [<branch-name>]

描述

如果给定 --list 选项，或者没有非选项参数，则会列出现有分支；当前分支将以绿色高亮显示并标记星号。在链接的工作树中检出的任何分支将以青色高亮显示并标记加号。选项 -r 会列出远程跟踪分支，而选项 -a 会显示本地和远程分支。

如果给定 <pattern>，它将用作 shell 通配符以将输出限制为匹配的分支。如果给定多个模式，只要分支与其中任何模式匹配，就会显示该分支。

请注意，在提供 <pattern> 时，您必须使用 --list；否则该命令可能被解释为分支创建。

使用 --contains 时，仅显示包含指定提交的分支（换句话说，其尖端提交是指定提交的后代的分支），--no-contains 则反转此功能。使用 --merged 时，仅列出已合并到指定提交中的分支（即其尖端提交可从指定提交到达的分支）。使用 --no-merged 时，仅列出未合并到指定提交中的分支。如果缺少 <commit> 参数，则默认为 HEAD（即当前分支的尖端）。

该命令的第二种形式会创建一个名为 <branch-name> 的新分支头，它指向当前的 HEAD，如果给定 <start-point> 则指向它。作为一种特殊情况，对于 <start-point>，如果正好有一个合并基础，您可以将 <rev-A>...<rev-B> 用作 <rev-A> 和 <rev-B> 合并基础的快捷方式。您最多可以省略 <rev-A> 和 <rev-B> 中的一个，在这种情况下它默认为 HEAD。

请注意，这会创建新分支，但不会将工作树切换到该分支；请使用 git switch <new-branch> 切换到新分支。

当一个本地分支从一个远程跟踪分支开始时，Git 会设置该分支（特别是 branch.<name>.remote 和 branch.<name>.merge 配置条目），以便 git pull 可以从远程跟踪分支进行适当合并。此行为可以通过全局 branch.autoSetupMerge 配置标志进行更改。该设置可以通过使用 --track 和 --no-track 选项来覆盖，并稍后使用 git branch --set-upstream-to 进行更改。

使用 -m 或 -M 选项时，<old-branch> 将被重命名为 <new-branch>。如果 <old-branch> 有相应的 reflog，它也会被重命名以匹配 <new-branch>，并创建一个 reflog 条目来记住分支重命名。如果 <new-branch> 已经存在，则必须使用 -M 来强制进行重命名。

-c 和 -C 选项的语义与 -m 和 -M 完全相同，不同之处在于分支不会被重命名，而是连同其配置和 reflog 一起复制到一个新名称。

使用 -d 或 -D 选项时，将删除 <branch-name>。您可以指定多个分支进行删除。如果分支当前有 reflog，则 reflog 也将被删除。

将 -r 与 -d 一起使用可删除远程跟踪分支。请注意，仅当远程跟踪分支在远程仓库中不再存在，或者 git fetch 已配置为不再抓取它们时，删除远程跟踪分支才有意义。另请参阅 git-remote[1] 的 prune 子命令，以了解清理所有过时远程跟踪分支的方法。

选项

-d
--delete

删除分支。该分支必须完全合并到其上游分支中，如果未通过 --track 或 --set-upstream-to 设置上游，则必须完全合并到 HEAD 中。

-D

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

--create-reflog

创建分支的 reflog。这会激活记录对分支引用所做的所有更改，从而支持使用基于日期的 sha1 表达式，例如 <branch-name>@{yesterday}。请注意，在非裸仓库中，reflog 通常通过 core.logAllRefUpdates 配置选项默认启用。反向形式 --no-create-reflog 仅覆盖较早的 --create-reflog，但目前不否定 core.logAllRefUpdates 的设置。

-f
--force

将 <branch-name> 重置为 <start-point>，即使 <branch-name> 已存在。如果没有 -f，git branch 会拒绝更改现有分支。与 -d（或 --delete）结合使用时，允许删除分支，无论其合并状态如何，或者它是否指向有效提交。与 -m（或 --move）结合使用时，即使新分支名称已存在，也允许重命名分支，-c（或 --copy）也适用相同规则。

请注意，即使使用 -f，git branch -f <branch-name> [<start-point>] 也拒绝更改在链接到同一仓库的另一个工作树中已检出的现有分支 <branch-name>。

-m
--move

移动/重命名分支，同时移动其配置和 reflog。

-M

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

-c
--copy

复制分支，同时复制其配置和 reflog。

-C

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

--color[=<when>]

为分支着色以突出显示当前、本地和远程跟踪分支。值必须是 always（默认值）、never 或 auto。

--no-color

关闭分支颜色，即使配置文件默认输出颜色。与 --color=never 相同。

-i
--ignore-case

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

--omit-empty

在格式化引用中，如果格式扩展为空字符串，则不在其后打印换行符。

--column[=<options>]
--no-column

以列形式显示分支列表。有关选项语法，请参阅配置变量 column.branch。--column 和不带选项的 --no-column 分别等同于 always 和 never。

此选项仅适用于非详细模式。

--sort=<key>

根据 <key> 排序。前缀 - 以降序排列。您可以多次使用 --sort=<key> 选项，在这种情况下，最后一个键成为主键。支持的键与 git-for-each-ref[1] 中的键相同。排序顺序默认为 branch.sort 变量配置的值（如果存在），否则基于完整的 refname（包括 refs/... 前缀）进行排序。这首先列出分离的 HEAD（如果存在），然后是本地分支，最后是远程跟踪分支。请参阅 git-config[1]。

-r
--remotes

列出或删除（如果与 -d 一起使用）远程跟踪分支。与 --list 结合使用以匹配可选模式。

-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 pull 从上游拉取。

确切的上游分支根据可选参数选择：-t、--track 或 --track=direct 意味着使用起点分支本身作为上游；--track=inherit 意味着复制起点分支的上游配置。

branch.autoSetupMerge 配置变量指定了当未指定 --track 也未指定 --no-track 时，git switch、git checkout 和 git branch 的行为方式。

默认选项 true 的行为如同在起点是远程跟踪分支时给定 --track=direct。false 的行为如同给定 --no-track。always 的行为如同给定 --track=direct。inherit 的行为如同给定 --track=inherit。simple 的行为如同仅当 <start-point> 是远程跟踪分支且新分支与远程分支同名时才给定 --track=direct。

有关 branch.<name>.remote 和 branch.<name>.merge 选项如何使用的更多讨论，请参阅 git-pull[1] 和 git-config[1]。

--no-track

即使设置了 branch.autoSetupMerge 配置变量，也不设置“上游”配置。

--recurse-submodules

此选项为实验性！如果启用了 submodule.propagateBranches，则使当前命令递归进入子模块。请参阅 git-config[1] 中的 submodule.propagateBranches。目前，仅支持分支创建。

在分支创建中使用时，将在超级项目中以及超级项目的 <start-point> 中的所有子模块中创建一个新分支 <branch-name>。在子模块中，该分支将指向超级项目的 <start-point> 中的子模块提交，但分支的跟踪信息将根据子模块的分支和远程设置，例如 git branch --recurse-submodules topic origin/main 将创建子模块分支“topic”，该分支指向超级项目的“origin/main”中的子模块提交，但跟踪子模块的“origin/main”。

--set-upstream

由于此选项的语法容易混淆，因此不再支持。请改用 --track 或 --set-upstream-to。

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

设置 <branch-name> 的跟踪信息，以便 <upstream> 被视为 <branch-name> 的上游分支。如果未指定 <branch-name>，则默认为当前分支。

--unset-upstream

移除 <branch-name> 的上游信息。如果未指定分支，则默认为当前分支。

--edit-description

打开编辑器并编辑文本以解释分支的用途，供各种其他命令使用（例如 format-patch、request-pull 和 merge（如果启用））。可以使用多行解释。

--contains [<commit>]

仅列出包含 <commit> 的分支（如果未指定，则为 HEAD）。隐含 --list。

--no-contains [<commit>]

仅列出不包含 <commit> 的分支（如果未指定，则为 HEAD）。隐含 --list。

--merged [<commit>]

仅列出其尖端可从 <commit> 访问的分支（如果未指定，则为 HEAD）。隐含 --list。

--no-merged [<commit>]

仅列出其尖端无法从 <commit> 访问的分支（如果未指定，则为 HEAD）。隐含 --list。

--points-at <object>

仅列出 <object> 的分支。

--format <format>

一个字符串，它会从显示的分支引用及其指向的对象中插入 %(fieldname)。<format> 与 git-for-each-ref[1] 中的相同。

<branch-name>

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

<start-point>

新分支头将指向此提交。它可以是分支名称、提交 ID 或标签。如果省略此选项，将使用当前的 HEAD。

<old-branch>

现有分支的名称。如果省略此选项，将使用当前分支的名称。

<new-branch>

现有分支的新名称。与 <branch-name> 相同的限制适用。

配置

pager.branch 仅在列出分支时受尊重，即当使用或隐含 --list 时。默认是使用分页器。请参阅 git-config[1]。

本节中此行以上的所有内容均未包含在 git-config[1] 文档中。以下内容与该文档中的内容相同

branch.autoSetupMerge

告诉 git branch、git switch 和 git checkout 设置新分支，以便 git-pull[1] 可以从起点分支适当合并。请注意，即使未设置此选项，也可以使用 --track 和 --no-track 选项为每个分支选择此行为。此选项默认为 true。有效设置为：

false

不进行自动设置

true

当起点是远程跟踪分支时进行自动设置

always

当起点是本地分支或远程跟踪分支时进行自动设置

inherit

如果起点具有跟踪配置，则将其复制到新分支

simple

仅当起点是远程跟踪分支且新分支与远程分支同名时才进行自动设置。

branch.autoSetupRebase

当使用 git branch、git switch 或 git checkout 创建一个跟踪另一个分支的新分支时，此变量告知 Git 将拉取设置为 rebase 而不是 merge（请参阅 branch.<name>.rebase）。有效设置为：

never

rebase 从不自动设置为 true。

local

对于其他本地分支的跟踪分支，rebase 设置为 true。

remote

对于远程跟踪分支的跟踪分支，rebase 设置为 true。

always

所有跟踪分支的 rebase 都将设置为 true。

有关如何设置分支以跟踪另一个分支的详细信息，请参阅 branch.autoSetupMerge。此选项默认为 never。

branch.sort

此变量控制 git-branch[1] 显示分支时的排序顺序。如果未提供 --sort=<value> 选项，则此变量的值将用作默认值。有关有效值，请参阅 git-for-each-ref[1] 字段名称。

branch.<name>.remote

在分支 <name> 上时，它告诉 git fetch 和 git push 从哪个远程仓库抓取或推送到哪个远程仓库。要推送到的远程仓库可以通过 remote.pushDefault（适用于所有分支）覆盖。对于当前分支，要推送到的远程仓库可以进一步通过 branch.<name>.pushRemote 覆盖。如果未配置远程仓库，或者您不在任何分支上并且仓库中定义了多个远程仓库，则抓取时默认为 origin，推送时默认为 remote.pushDefault。此外，.（一个句点）是当前的本地仓库（一个点仓库），请参阅下面 branch.<name>.merge 的最后一条说明。

branch.<name>.pushRemote

在分支 <name> 上时，它会覆盖用于推送的 branch.<name>.remote。它还会覆盖从分支 <name> 推送的 remote.pushDefault。当您从一个地方拉取（例如您的上游）并推送到另一个地方（例如您自己的发布仓库）时，您会希望设置 remote.pushDefault 来指定所有分支的推送远程仓库，并使用此选项来覆盖特定分支的设置。

branch.<name>.merge

与 branch.<name>.remote 一起，定义给定分支的上游分支。它告诉 git fetch/git pull/git rebase 要合并哪个分支，并且也可以影响 git push（请参阅 push.default）。在分支 <name> 中时，它告诉 git fetch 在 FETCH_HEAD 中标记为合并的默认 refspec。该值的处理方式类似于 refspec 的远程部分，并且必须与从 branch.<name>.remote 给定的远程仓库抓取的引用匹配。合并信息由 git pull（它首先调用 git fetch）用于查找默认合并分支。如果没有此选项，git pull 默认为合并第一个抓取的 refspec。指定多个值以获得章鱼合并。如果您希望设置 git pull 以便它从本地仓库中的另一个分支合并到 <name> 中，您可以将 branch.<name>.merge 指向所需的分支，并为 branch.<name>.remote 使用相对路径设置 .（一个句点）。

branch.<name>.mergeOptions

设置合并到分支 <name> 的默认选项。语法和支持的选项与 git-merge[1] 的相同，但目前不支持包含空格字符的选项值。

branch.<name>.rebase

如果为 true，当运行 git pull 时，将分支 <name> rebase 到抓取的分支之上，而不是合并来自默认远程仓库的默认分支。有关以非分支特定方式执行此操作的详细信息，请参阅 pull.rebase。

当为 merges（或简写 m）时，将 --rebase-merges 选项传递给 git rebase，以便本地合并提交包含在 rebase 中（详情请参阅 git-rebase[1]）。

当值为 interactive（或简写 i）时，rebase 以交互模式运行。

注意：这是一个可能危险的操作；除非您了解其影响，否则不要使用它（详情请参阅 git-rebase[1]）。

branch.<name>.description

分支描述，可以使用 git branch --edit-description 进行编辑。分支描述会自动添加到 format-patch 封面信或 request-pull 摘要中。

示例

从已知标签开始开发
$ 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”。除非您将它们配置为不创建，否则下次 git fetch 或 git pull 将再次创建它们。请参阅 git-fetch[1]。

  2. 删除“test”分支，即使“master”分支（或当前检出的任何分支）不包含来自 test 分支的所有提交。

列出特定远程仓库的分支
$ 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]

模式通常需要加引号。

注意事项

如果您正在创建一个希望立即切换到的分支，使用 git switch 命令及其 -c 选项可以更轻松地通过一个命令完成相同的操作。

选项 --contains、--no-contains、--merged 和 --no-merged 有四个相关但不同的用途

  • --contains <commit> 用于查找所有需要特别注意的分支，如果 <commit> 要进行 rebase 或修改，因为这些分支包含指定的 <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 用户手册中的 “理解历史：什么是分支？”。

GIT

Git[1] 套件的一部分

scroll-to-top