简体中文 ▾ 主题 ▾ 最新版本 ▾ 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}。请注意，在非纯仓库中，通常默认通过 core.logAllRefUpdates 配置选项启用 reflog。否定形式 --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 变量配置的值，则排序顺序默认为该值，否则默认为基于完整引用名称（包括 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。

参见 git-pull[1] 和 git-config[1] 以了解关于如何使用 branch.<name>.remote 和 branch.<name>.merge 选项的进一步讨论。

--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 哪些默认 refspec 将在 FETCH_HEAD 中被标记为待合并。该值的处理方式类似于 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> 变基到获取到的分支之上，而不是合并来自默认远程仓库的默认分支。请参见 pull.rebase 以非分支特异性的方式执行此操作。

当为 merges（或仅为 m）时，向 git rebase 传递 --rebase-merges 选项，以便在变基中包含本地合并提交（详情参见 git-rebase[1]）。

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

注意：这可能是一个危险的操作；除非您理解其影响，否则请勿使用（详情参见 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. 即使 "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] 套件的一部分