English ▾ 主题 ▾ 最新版本 ▾ 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 显示本地和远程分支。

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

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

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

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

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

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

使用 -m 或 -M 选项，<oldbranch> 将被重命名为 <newbranch>。 如果 <oldbranch> 具有相应的 reflog，则会重命名它以匹配 <newbranch>，并创建一个 reflog 条目以记住分支重命名。 如果 <newbranch> 存在，则必须使用 -M 来强制重命名发生。

-c 和 -C 选项具有与 -m 和 -M 完全相同的语义，除了分支将被复制到新名称，而不是被重命名，以及其配置和 reflog。

使用 -d 或 -D 选项，<branchname> 将被删除。 您可以指定要删除的多个分支。 如果分支当前具有 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 表达式，例如 "<branchname>@{yesterday}"。 请注意，在非裸存储库中，reflog 通常默认由 core.logAllRefUpdates 配置选项启用。 取反形式 --no-create-reflog 仅覆盖较早的 --create-reflog，但目前不会否定 core.logAllRefUpdates 的设置。

-f
--force

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

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

-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。

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

-r
--remotes

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

-a
--all

同时列出远程跟踪分支和本地分支。与 --list 结合使用可以匹配可选的模式。

-l
--list

列出分支。带有可选的 <pattern>...，例如 git branch --list 'maint-*'，仅列出与模式匹配的分支。

--show-current

打印当前分支的名称。在分离 HEAD 状态下，不打印任何内容。

-v
-vv
--verbose

在列表模式下，显示每个 head 的 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，则导致当前命令递归到子模块中。请参阅 git-config[1] 中的 submodule.propagateBranches。目前，仅支持分支创建。

在分支创建中使用时，将在超级项目中和超级项目的 <start-point> 中的所有子模块中创建一个新分支 <branchname>。在子模块中，该分支将指向超级项目的 <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>

设置 <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>

新分支 head 将指向此提交。可以将其作为分支名称、提交 ID 或标签给出。如果省略此选项，则将改用当前的 HEAD。

<oldbranch>

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

<newbranch>

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

--sort=<key>

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

--points-at <object>

仅列出给定对象的分支。

--format <format>

一个字符串，用于从正在显示的分支引用及其指向的对象中插入 %(fieldname)。格式与 git-for-each-ref[1] 的格式相同。

配置

pager.branch 仅在列出分支时才有效，即当使用或暗示 --list 时。默认是使用分页器。请参阅 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 而不是 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" 给出的远程仓库拉取的 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 时，将 <name> 分支变基到拉取的分支之上，而不是在运行 "git pull" 时从默认远程仓库合并默认分支。 有关以非分支特定的方式执行此操作，请参见 "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 封面或 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"。 除非你配置它们不要创建，否则下一个 fetch 或 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] 套件的一部分

scroll-to-top