简体中文 ▾ 主题 ▾ 最新版本 ▾ git-branch 上次更新于 2.51.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>。特殊情况下，对于 <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

删除一个分支。该分支必须已完全合并到其上游分支，或者合并到 HEAD（如果未使用 --track 或 --set-upstream-to 设置上游）。

-D

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

--create-reflog

创建分支的 reflog。这会激活对分支 ref 所做的所有更改的记录，从而能够使用基于日期的 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）。

请注意，git branch -f <branch-name> [<start-point>]，即使带有 -f，也会拒绝更改同一个仓库链接的另一个工作树中已签出的现有分支 <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 的行为是仅当开始点是远程跟踪分支且新分支的名称与远程分支的名称相同时，给出 --track=direct。

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

--no-track

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

--recurse-submodules

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

在创建分支时，将在父项目及其所有子模块的 <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>

一个字符串，用于内插显示的分支 ref 和其指向的对象中的 %(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 以进行推送。它还覆盖 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> 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 或 amended，需要特别注意的所有分支，因为那些分支包含指定的 <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] 套件的一部分