简体中文 ▾ 主题 ▾ 最新版本 ▾ git-switch 最后更新于 2.55.0

名称

git-switch - 切换分支

概要

git switch [<options>] [--no-guess] <branch>
git switch [<options>] --detach [<start-point>]
git switch [<options>] (-c|-C) <new-branch> [<start-point>]
git switch [<options>] --orphan <new-branch>

描述

切换到指定分支。工作区和索引将被更新以匹配该分支。所有新的提交都将添加到此分支的末端。

可以选择通过 -c、-C 创建新分支，或者从同名的远程分支自动创建（参见 --guess），也可以通过 --detach 将工作区与任何分支分离，同时进行切换。

切换分支不需要索引和工作区保持干净（即不需要与 HEAD 没有任何差异）。但是，如果该操作会导致本地变更丢失，则会中止，除非通过 --discard-changes 或 --merge 指定强制执行。

选项

<branch>

要切换到的分支。

<new-branch>

新分支的名称。

<start-point>

新分支的起点。指定 <start-point> 允许您基于历史记录中除 HEAD 当前指向之外的某个点创建分支。（或者，在 --detach 的情况下，允许您检查并从其他某个点分离。）

您可以使用 @{-<N>} 语法来引用使用 git switch 或 git checkout 操作切换到的倒数第 <N> 个分支/提交。您也可以指定 -，它等同于 @{-1}。这通常用于在两个分支之间快速切换，或撤销错误的分支切换。

作为特殊情况，如果存在且仅存在一个合并基点，您可以使用 <rev-a>...<rev-b> 作为 <rev-a> 和 <rev-b> 合并基点的快捷方式。您可以省略 <rev-a> 和 <rev-b> 中的至多一个，此时它默认为 HEAD。

-c <new-branch>
--create <new-branch>

在切换到该分支之前，创建一个名为 <new-branch> 的新分支，并以 <start-point> 为起点。这是事务性的等价操作：

$ git branch <new-branch>
$ git switch <new-branch>

也就是说，除非 git switch 成功，否则分支不会被重置/创建（例如，当该分支在另一个工作树中使用时，不仅当前分支保持不变，该分支也不会被重置为起点）。

-C <new-branch>
--force-create <new-branch>

类似于 --create，区别在于如果 <new-branch> 已经存在，它将被重置为 <start-point>。这是一个方便的快捷方式：

$ git branch -f _<new-branch>_
$ git switch _<new-branch>_
-d
--detach

切换到提交以进行检查和可丢弃的实验。有关详细信息，请参阅 git-checkout[1] 中的“分离的 HEAD (DETACHED HEAD)”部分。

--guess
--no-guess

如果找不到 <branch>，但恰好在一个远程仓库（称为 <remote>）中存在名称匹配的跟踪分支，则将其视为等同于：

$ git switch -c <branch> --track <remote>/<branch>

如果分支存在于多个远程仓库中，且其中一个由 checkout.defaultRemote 配置变量命名，我们将使用该远程仓库进行歧义消除，即使 <branch> 在所有远程仓库中并不唯一。将其设置为如 checkout.defaultRemote=origin，以便在 <branch> 有歧义但在 origin 远程仓库中存在时，总是从那里检出远程分支。另请参阅 git-config[1] 中的 checkout.defaultRemote。

--guess 是默认行为。使用 --no-guess 禁用它。

默认行为可以通过 checkout.guess 配置变量进行设置。

-f
--force

--discard-changes 的别名。

--discard-changes

即使索引或工作区与 HEAD 不同也继续操作。索引和工作区都将被恢复以匹配切换目标。如果指定了 --recurse-submodules，子模块内容也会被恢复以匹配切换目标。这用于丢弃本地修改。

-m
--merge

如果您对一个或多个文件进行了本地修改，且这些修改在当前分支和要切换到的分支之间不同，该命令通常会拒绝切换分支以保留您的修改。但是，使用此选项，冲突的本地修改会在切换前自动暂存（stash），并在切换后重新应用。如果本地修改与分支间的差异不重叠，则无需暂存即可直接切换。如果重新应用暂存导致冲突，该条目将保存到暂存列表中。完成后解决冲突并运行 git stash drop，或者在运行 git stash pop 重新应用您的更改之前清理工作区（例如使用 git reset --hard）。

--conflict=<style>

与上面的 --merge 选项相同，但会更改冲突块的呈现方式，覆盖 merge.conflictStyle 配置变量。可能的值包括 merge（默认）、diff3 和 zdiff3。

-q
--quiet

安静模式，抑制反馈消息。

--progress
--no-progress

默认情况下，如果进度状态流被连接到终端，则进度状态会显示在标准错误流上，除非指定了 --quiet。此标志即使未连接到终端也会启用进度报告，无论 --quiet 如何。

-t
--track[ (direct|inherit)]

创建新分支时，设置“上游”配置。-c 为默认隐含选项。有关详细信息，请参阅 git-branch[1] 中的 --track。

如果没有给出 -c 选项，新分支的名称将从远程跟踪分支派生，方法是查看为相应远程仓库配置的引用规范的本地部分，并剥离直到“*”的初始部分。这意味着从 origin/hack（或 remotes/origin/hack，甚至 refs/remotes/origin/hack）分支出来时，我们将使用 hack 作为本地分支。如果给定的名称没有斜杠，或者上述猜测结果为空，则猜测中止。在这种情况下，您可以显式使用 -c 指定名称。

--no-track

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

--orphan <new-branch>

创建一个名为 <new-branch> 的未出生（unborn）分支。所有被跟踪的文件都将被移除。

--ignore-other-worktrees

当所需的引用已被另一个工作树检出时，git switch 会拒绝操作。此选项使其强制检出该引用。换句话说，该引用可以由多个工作树持有。

--recurse-submodules
--no-recurse-submodules

使用 --recurse-submodules 将根据超级项目（superproject）中记录的提交更新所有活动子模块的内容。如果未指定（或使用 --no-recurse-submodules），子模块的工作区将不会被更新。就像 git-submodule[1] 一样，这将分离子模块的 HEAD。

示例

以下命令切换到“master”分支：

$ git switch master

在错误的分支上工作后，切换到正确分支的操作为：

$ git switch mytopic

但是，您的“错误”分支和正确的“mytopic”分支可能在您本地修改的文件上存在差异，在这种情况下，上述切换将失败，提示如下：

$ git switch mytopic
error: You have local changes to 'frotz'; not switching branches.

您可以为该命令添加 -m 标志，它会将您的本地修改带到新分支：

$ git switch -m mytopic
Applied autostash.
Switched to branch 'mytopic'
The following paths have local changes:
M	frotz

切换后，本地修改会被重新应用，且不会注册在您的索引文件中，因此 git diff 会显示您自新分支末端以来所做的更改。

要切换回切换到 mytopic 之前所在的分支（即“master”分支）：

$ git switch -

您可以从任何提交增长出一个新分支。例如，切换到“HEAD~3”并创建分支“fixup”：

$ git switch -c fixup HEAD~3
Switched to a new branch 'fixup'

如果您想从同名的远程分支开始创建一个新分支：

$ git switch new-topic
Branch `new-topic` set up to track remote branch `new-topic` from `origin`
Switched to a new branch `new-topic`

要检出提交 HEAD~3 进行临时检查或实验而不创建新分支：

$ git switch --detach HEAD~3
HEAD is now at 9fc9555312 Merge branch 'cc/shared-index-permbits'

如果事实证明您的操作值得保留，您可以随时为它创建一个新名称（无需切换离开）：

$ git switch -c good-surprises

配置

本节中以下所有内容均从 git-config[1] 文档中选择性地包含。内容与彼处相同：

checkout.defaultRemote

当您运行 git checkout <something> 或 git switch <something> 且只有一个远程时，它可能会隐式地回退到签出和跟踪 e.g. origin/<something>。一旦您有多个具有 *<something>* 引用的远程，这种情况就会停止工作。此设置允许设置一个首选远程的名称，该名称在歧义化时应始终优先。典型用例是将其设置为 origin。

目前，它由 git-switch[1] 和 git-checkout[1] 使用，当 git checkout <something> 或 git switch <something> 会签出另一个远程上的 *<something>* 分支时，以及由 git-worktree[1] 使用，当 git worktree add 指的是远程分支时。此设置将来可能会用于其他类似 checkout 的命令或功能。

checkout.guess

为 git checkout 和 git switch 命令中的 --guess 或 --no-guess 选项提供默认值。参见 git-switch[1] 和 git-checkout[1]。

checkout.workers

更新工作树时使用的并行工作进程数量。默认为一个，即顺序执行。如果设置为小于一的值，Git 将使用与可用逻辑核心数相同的数量的工作进程。此设置和 checkout.thresholdForParallelism 会影响所有执行 checkout 的命令。例如：checkout、clone、reset、sparse-checkout 等。

注意
 并行 checkout 通常可以提高位于 SSD 或 NFS 上的存储库的性能。对于旋转硬盘和/或核心数较少的机器上的存储库，默认的顺序 checkout 通常性能更好。存储库的大小和压缩级别也可能影响并行版本的性能。
checkout.thresholdForParallelism

当使用少量文件进行并行 checkout 时，子进程生成和进程间通信的成本可能会超过并行化的收益。此设置允许您定义应尝试并行 checkout 的最小文件数。默认值为 100。

另请参阅

git-checkout[1], git-branch[1]

GIT

Git[1] 套件的一部分