简体中文 ▾ 主题 ▾ 最新版本 ▾ 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>，如果恰好有一个合并基点，你可以使用 <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）。

请注意，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。

此选项仅适用于非详细 (non-verbose) 模式。

--sort=<key>

根据 <key> 排序。前缀 - 表示按值的降序排列。你可以多次使用 --sort=<key> 选项，在这种情况下，最后一个键成为主键。支持的键与 git-for-each-ref[1] 中的键相同。排序顺序默认为 branch.sort 变量中配置的值（如果存在），或者基于完整的引用名称（包括 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> 相同的限制。

配置

仅在列出分支时（即使用或隐含 --list 时）才会遵守 pager.branch。默认是使用分页器。参见 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 设置 pull 为变基 (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 默认的引用规格（refspec），以便在 FETCH_HEAD 中标记为待合并。该值的处理方式类似于引用规格的远程部分，并且必须匹配从 branch.<name>.remote 给出的远程仓库中获取的引用。合并信息由 git pull（它首先调用 git fetch）用于查找合并的默认分支。如果没有此选项，git pull 默认合并获取到的第一个引用规格。指定多个值可以获得章鱼合并（octopus merge）。如果你希望设置 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，以便本地合并提交包含在变基中（详情参见 git-rebase[1]）。

当值为 interactive（或仅为 i）时，变基以交互模式运行。

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

branch.<name>.description

分支描述，可以使用 git branch --edit-description 进行编辑。分支描述会自动添加到 format-patch 的附信（cover letter）或 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. 即使 "master" 分支（或当前检出的任何分支）不包含 test 分支的所有提交，也要删除 "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]

模式通常需要加引号。

注意事项

如果你正在创建一个想要立即切换到的分支，那么使用带有 -c 选项的 git switch 命令通过单个命令执行相同的操作会更容易。

选项 --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

Git[1] 套件的一部分