Git

git-branch 最后更新于 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] <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 会显示本地分支和远程分支。

如果给出 <模式>，则将其用作 shell 通配符以将输出限制为匹配的分支。如果给出多个模式，则如果分支匹配任何模式，则会显示该分支。

注意，在提供 <模式> 时，你必须使用 --list；否则命令可能会被解释为分支创建。

使用 --contains 时，只显示包含指定提交的分支（换句话说，其顶端提交是指定提交的后代的分支），--no-contains 会反转它。使用 --merged 时，只会列出合并到指定提交的分支（即其顶端提交可以从指定提交访问的分支）。使用 --no-merged 时，只会列出未合并到指定提交的分支。如果 <提交> 参数缺失，则默认为 HEAD（即当前分支的顶端）。

该命令的第二种形式创建一个名为 <分支名称> 的新分支头，它指向当前 HEAD，或者如果给出则指向 <起点>。作为特例，对于 <起点>，你可以使用 "A...B" 作为 A 和 B 的合并基的快捷方式，如果只有一个合并基。你可以省略最多一个 A 或 B，在这种情况下它默认为 HEAD。

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

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

使用 -m 或 -M 选项时，<旧分支> 将重命名为 <新分支>。如果 <旧分支> 有对应的 reflog，则会重命名以匹配 <新分支>，并且会创建一个 reflog 条目来记录分支重命名。如果 <新分支> 存在，则必须使用 -M 来强制重命名发生。

-c 和 -C 选项与 -m 和 -M 的语义完全相同，除了分支被重命名之外，它将被复制到一个新名称，以及它的配置和 reflog。

使用 -d 或 -D 选项时，将删除 <分支名称>。你可以指定多个分支进行删除。如果分支当前有一个 reflog，则也会删除该 reflog。

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

选项

-d
--delete: 删除分支。分支必须完全合并到其上游分支中，或者如果使用 --track 或 --set-upstream-to 设置了上游分支，则合并到 HEAD 中。
-D: --delete --force 的快捷方式。
--create-reflog: 创建分支的 reflog。这会激活对对分支 ref 所做的所有更改进行记录，从而可以根据日期使用 sha1 表达式，例如 "<分支名称>@{yesterday}"。请注意，在非裸存储库中，reflog 通常默认通过 core.logAllRefUpdates 配置选项启用。否定形式 --no-create-reflog 只会覆盖早期的 --create-reflog，但目前不会否定 core.logAllRefUpdates 的设置。
-f
--force: 将 <分支名称> 重置为 <起点>，即使 <分支名称> 已经存在。如果没有 -f，git branch 拒绝更改现有分支。与 -d（或 --delete）结合使用时，允许删除分支，无论其合并状态如何，或是否甚至指向有效的提交。与 -m（或 --move）结合使用时，允许重命名分支，即使新分支名称已经存在，-c（或 --copy）也是如此。

请注意，git branch -f <分支名称> [<起点>]，即使使用 -f，也拒绝更改在链接到同一存储库的另一个工作树中签出的现有分支 <分支名称>。
-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: 在格式化的 refs 之后不打印换行符，其中格式扩展为空字符串。
--column[=<options>]
--no-column: 以列的形式显示分支列表。有关选项语法，请参阅配置变量 column.branch。--column 和 --no-column 不带选项分别等同于 always 和 never。

此选项仅适用于非详细模式。
-r
--remotes: 列出或删除（如果与 -d 一起使用）远程跟踪分支。与 --list 结合使用以匹配可选模式。
-a
--all: 列出远程跟踪分支和本地分支。与 --list 结合使用以匹配可选模式。
-l
--list: 列出分支。使用可选的 <模式>...，例如 git branch --list 'maint-*'，只列出匹配模式的分支。
--show-current: 打印当前分支的名称。在分离的 HEAD 状态下，不打印任何内容。
-v
-vv
--verbose: 在列表模式下，显示每个头的 sha1 和提交主题行，以及与上游分支的关系（如果有）。如果给出两次，则还会打印链接的工作树的路径（如果有）以及上游分支的名称（另请参阅 git remote show <远程>）。请注意，当前工作树的 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 配置变量指定 git switch、git checkout 和 git branch 在未指定 --track 或 --no-track 时应如何行为。

默认选项 true 行为类似于在起点是远程跟踪分支时给出 --track=direct。false 的行为类似于给出 --no-track。always 的行为类似于给出 --track=direct。inherit 的行为类似于给出 --track=inherit。simple 的行为类似于仅在起点是远程跟踪分支并且新分支与远程分支同名时给出 --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。目前，仅支持分支创建。

在分支创建中使用时，将在超级项目中创建新分支 <branchname>，以及超级项目 <start-point> 中的所有子模块。在子模块中，该分支将指向超级项目 <start-point> 中的子模块提交，但该分支的跟踪信息将根据子模块的分支和远程设置，例如 git branch --recurse-submodules topic origin/main 将创建指向超级项目 "origin/main" 中的子模块提交的子模块分支 "topic"，但跟踪子模块的 "origin/main"。
--set-upstream: 由于此选项的语法令人困惑，因此不再支持。请改用 --track 或 --set-upstream-to。
-u <upstream>
--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] 定义的所有检查。其中一些检查可能会限制分支名称中允许的字符。
<start-point>: 新分支头将指向此提交。它可以作为分支名称、提交 ID 或标签给出。如果省略此选项，将使用当前 HEAD。
<oldbranch>: 现有分支的名称。如果省略此选项，将使用当前分支的名称。
<newbranch>: 现有分支的新名称。与 <branchname> 相同的限制适用。
--sort=<key>: 根据给定的键排序。添加前缀 - 以按值的降序排序。您可以多次使用 --sort=<key> 选项，在这种情况下，最后一个键成为主键。支持的键与 git for-each-ref 中的相同。排序顺序默认为 branch.sort 变量的配置值（如果存在），或者根据完整 refname（包括 refs/... 前缀）排序。这会首先列出分离的 HEAD（如果存在），然后是本地分支，最后是远程跟踪分支。请参阅 git-config[1]。
--points-at <object>: 仅列出给定对象的 Branches。
--format <format>: 一个字符串，它插值来自显示的分支 ref 和其指向的对象的 %(fieldname)。格式与 git-for-each-ref[1] 的相同。

配置

pager.branch 仅在列出分支时受到尊重，即，当使用或隐含 --list 时。默认情况下，使用一个 pager。请参阅 git-config[1]。

本节中本行以上的内容不包含在 git-config[1] 文档中。以下内容与在该文档中找到的内容相同。

branch.autoSetupMerge: 告诉 git branch、git switch 和 git checkout 设置新分支，以便 git-pull[1] 可以适当地从起点分支合并。请注意，即使未设置此选项，也可以使用 --track 和 --no-track 选项，在每个分支选择此行为。有效设置是：false - 不进行自动设置；true - 在起点是远程跟踪分支时进行自动设置；always - 在起点是本地分支或远程跟踪分支时进行自动设置；inherit - 如果起点有跟踪配置，则将其复制到新分支；simple - 仅在起点是远程跟踪分支并且新分支与远程分支同名时进行自动设置。此选项默认为 true。
branch.autoSetupRebase: 当使用 git branch、git switch 或 git checkout 创建一个跟踪另一个分支的新分支时，此变量告诉 Git 设置 pull 以进行 rebase 而不是合并（参见“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 以进行推送。它还会覆盖 remote.pushDefault 以从分支 <name> 推送。当您从一个地方拉取（例如您的上游）并推送到另一个地方（例如您自己的发布存储库）时，您可能希望设置 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" 给出的远程获取的 ref 匹配。合并信息由 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>，而不是合并来自默认远程的默认分支。请参阅 "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

此步骤和下一步可以合并为一个步骤，使用 "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"。除非您将其配置为不这样做，否则下次获取或拉取将再次创建它们。请参阅 git-fetch[1]。
即使 "master" 分支（或当前签出的任何分支）没有来自 "test" 分支的所有提交，也要删除 "test" 分支。

列出特定远程的分支

$ git branch -r -l '<remote>/<pattern>'                 (1)
$ git for-each-ref 'refs/remotes/<remote>/<pattern>'    (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 用户手册中。

是 git[1] 套件的一部分

设置和配置

获取和创建项目

基本快照

分支和合并

共享和更新项目

检查和比较

补丁

调试

电子邮件

外部系统

服务器管理

指南

管理

底层命令

名称

概要

描述

选项

配置

示例

注意

另请参阅

GIT

branch