Git
简体中文 ▾ Topics ▾ Latest version ▾ git-branch last updated in 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] <分支名> [<起始点>]
git branch (--set-upstream-to=<上游> | -u <上游>) [<分支名>]
git branch --unset-upstream [<分支名>]
git branch (-m | -M) [<旧分支>] <新分支>
git branch (-c | -C) [<旧分支>] <新分支>
git branch (-d | -D) [-r] <分支名>…​
git branch --edit-description [<分支名>]

描述

If --list is given, or if there are no non-option arguments, existing branches are listed; the current branch will be highlighted in green and marked with an asterisk. Any branches checked out in linked worktrees will be highlighted in cyan and marked with a plus sign. Option -r causes the remote-tracking branches to be listed, and option -a shows both local and remote branches.

如果给出了`<pattern>`,它被用作shell通配符,将输出限制在匹配的分支上。如果给出多个模式,如果一个分支与任何模式相匹配,就会显示出来。

注意,当提供"<pattern>"时,必须使用"--list";否则命令可能被解释为创建分支。

With --contains, shows only the branches that contain the named commit (in other words, the branches whose tip commits are descendants of the named commit), --no-contains inverts it. With --merged, only branches merged into the named commit (i.e. the branches whose tip commits are reachable from the named commit) will be listed. With --no-merged only branches not merged into the named commit will be listed. If the <commit> argument is missing it defaults to HEAD (i.e. the tip of the current branch).

该命令的第二种形式是创建一个名为<branchname>的新分支头,该分支头指向当前的`HEAD`,如果给定的话,则指向<start-point>。作为一种特殊情况,对于<start-point>,你可以使用`"A…​B "作为`A`和`B`的合并基础的快捷方式,如果正好有一个合并基础。你最多可以省略`A`和`B`中的一个,在这种情况下,它默认为`HEAD`。

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

当一个本地分支从远程跟踪的分支开始时,Git 会设置该分支(特别是 branch.<name>.remotebranch.<name>.merge 配置项),以便 "git pull "能适当地从远程跟踪的分支合并。这种行为可以通过全局的 branch.autoSetupMerge 配置标志来改变。该设置可以通过使用`--track`和`--no-track`选项来覆盖,并在之后使用`git branch --set-upstream-to`来改变。

With a -m or -M option, <oldbranch> will be renamed to <newbranch>. If <oldbranch> had a corresponding reflog, it is renamed to match <newbranch>, and a reflog entry is created to remember the branch renaming. If <newbranch> exists, -M must be used to force the rename to happen.

-c`和-C`选项的语义与`-m`和`-M`完全相同,只不过不是对分支进行重命名,而是将其连同其配置和日志一起复制到一个新的名称。

With a -d or -D option, <branchname> will be deleted. You may specify more than one branch for deletion. If the branch currently has a reflog then the reflog will also be deleted.

使用 -r-d 来删除远程跟踪的分支。注意,只有当远程分支不再存在于远程仓库或 "git fetch "被配置为不再获取它们时,删除远程跟踪分支才有意义。参见 git-remote[1] 的 "prune "子命令,它可以清理所有过时的远程跟踪分支。

选项

-d
--delete

删除一个分支。该分支必须完全合并在其上游分支中,如果没有用`--track`或`--set-upstream-to`设置的上游分支,则必须在`HEAD`中。

-D

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

--create-reflog

Create the branch’s reflog. This activates recording of all changes made to the branch ref, enabling use of date based sha1 expressions such as "<branchname>@{yesterday}". Note that in non-bare repositories, reflogs are usually enabled by default by the core.logAllRefUpdates config option. The negated form --no-create-reflog only overrides an earlier --create-reflog, but currently does not negate the setting of core.logAllRefUpdates.

-f
--force

Reset <branchname> to <start-point>, even if <branchname> exists already. Without -f, git branch refuses to change an existing branch. In combination with -d (or --delete), allow deleting the branch irrespective of its merged status, or whether it even points to a valid commit. In combination with -m (or --move), allow renaming the branch even if the new branch name already exists, the same applies for -c (or --copy).

请注意,"git branch -f <branchname> [<start-point>]"命令,即使添加"-f"选项,该命令也会拒绝改变一个在链接到同一仓库的另一个工作树中被检查出来的现有分支`<branchname>`。

-m
--move

移动/重命名分支及其配置和引用日志。

-M

`--move --force`的快捷方式。

-c
--copy

复制分支及其配置和引用日志。

-C

`--copy --force`的快捷方式。

--color[=<when>]

Color branches to highlight current, local, and remote-tracking branches. The value must be always (the default), never, or auto.

--no-color

Turn off branch colors, even when the configuration file gives the default to color output. Same as --color=never.

-i
--ignore-case

排序和过滤分支是不分大小写的。

--omit-empty

在格式化的引用后不打印换行,因为格式化的引用会扩展为空字符串。

--column[=<选项>]
--no-column

在列中显示分支列表。选项语法见配置变量`column.branch`。--column`和--no-column`没有选项,分别相当于’always’和’never'。

这个选项只适用于非粗话模式。

-r
--remotes

List or delete (if used with -d) the remote-tracking branches. Combine with --list to match the optional pattern(s).

-a
--all

List both remote-tracking branches and local branches. Combine with --list to match optional pattern(s).

-l
--list

List branches. With optional <pattern>..., e.g. git branch --list 'maint-*', list only the branches that match the pattern(s).

--show-current

打印当前分支的名称。在分离的HEAD状态下,不打印任何东西。

-v
-vv
--verbose

When in list mode, show sha1 and commit subject line for each head, along with relationship to upstream branch (if any). If given twice, print the path of the linked worktree (if any) and the name of the upstream branch, as well (see also git remote show <remote>). Note that the current worktree’s HEAD will not have its path printed (it will always be your current directory).

-q
--quiet

在创建或删除一个分支时更加安静,抑制非错误信息。

--abbrev=<n>

In the verbose listing that show the commit object name, show the shortest prefix that is at least <n> hexdigits long that uniquely refers the object. The default value is 7 and can be overridden by the core.abbrev config option.

--no-abbrev

在输出列表中显示完整的sha1,而不是缩写它们。

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

在创建一个新分支时,设置 branch.<name>.remotebranch.<name>.merge 配置项来为新分支设置“上游”追踪。这个配置将告诉 git 在 git statusgit branch -v 中显示这两个分支之间的关系(译者注:应该是 git branch -vv 命令而不是 git branch -v 命令,这样才会显示某一分支的上游)。此外,它还指示了在该新分支上运行不带参数的 git pull 命令时,将直接从上游拉取。

想要选择确切的上游分支可以使用可选参数:-t--track--track=direct,这些参数均表示使用 <start-point> 分支本身作为上游分支;--track=inherit 表示继承 <start-point> 分支的上游配置。

branch.autoSetupMerge配置变量指定了当既不指定`--track`也不指定`--no-track`时,git switch、`git checkout`和`git branch`应如何运行:

The default option, true, behaves as though --track=direct were given whenever the start-point is a remote-tracking branch. false behaves as if --no-track were given. always behaves as though --track=direct were given. inherit behaves as though --track=inherit were given. simple behaves as though --track=direct were given only when the start-point is a remote-tracking branch and the new branch has the same name as the remote branch.

有关如何使用 branch.<名称>.remotebranch.<名称>.merge 选项的更多讨论,请参见 git-pull[1]git-config[1]

--no-track

不要设置 “上游仓库” 配置,即使 branch.autoSetupMerge 配置变量为 true。

--recurse-submodules

这个选项是实验性的!!!如果 submodule.propagateBranches 被启用,会导致当前命令递归到子模块。参见 git-config[1] 中的 submodule.propagateBranches。目前,只支持创建分支。

当在分支创建中使用时,一个新的分支<branchname>将在父项目和父项目的<start-point>中的所有子模块中创建。在子模块中,该分支将指向超级项目的<start-point>中的子模块提交,但该分支的跟踪信息将根据子模块的分支和远程来设置,例如`git branch --recurse-submodules topic origin/main`将创建一个子模块分支 "topic",指向父项目的 "origin/main "中的子模块提交,但跟踪子模块的 "origin/main"。

--set-upstream

As this option had confusing syntax, it is no longer supported. Please use --track or --set-upstream-to instead.

-u <上行>
--set-upstream-to=<上游仓库>

设置<branchname>的跟踪信息,使<upstream>被视为<branchname>的上游分支。如果没有指定<branchname>,则默认为当前分支。

--unset-upstream

删除<branchname>的上游信息。如果没有指定分支,则默认为当前分支。

--edit-description

打开一个编辑器,编辑文本,解释该分支的用途,以便被其他各种命令(如`format-patch`、request-pull`和`merge(如果启用))使用。可以使用多行解释。

--contains [<提交>]

只列出包含指定提交的分支(如果没有指定则为HEAD)。意味着 --list

--no-contains [<提交>]

只列出不包含指定提交的分支(如果不指定则为HEAD)。意味着 --list

--merged [<提交>]

只列出从指定的提交(如果没有指定,则为HEAD)可以到达的分支的提示。意味着 --list

--no-merged [<提交>]

只列出从指定的提交(如果没有指定,则为HEAD)中无法到达的分支。意味着 --list

<branchname>

The name of the branch to create or delete. The new branch name must pass all checks defined by git-check-ref-format[1]. Some of these checks may restrict the characters allowed in a branch name.

<start-point>

The new branch head will point to this commit. It may be given as a branch name, a commit-id, or a tag. If this option is omitted, the current HEAD will be used instead.

<旧分支>

The name of an existing branch. If this option is omitted, the name of the current branch will be used instead.

<新分支>

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

--sort=<键>

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

--points-at <对象>

只列出给定对象的分支。

--format <格式>

A string that interpolates %(fieldname) from a branch ref being shown and the object it points at. The format is the same as that of git-for-each-ref[1].

配置

pager.branch is only respected when listing branches, i.e., when --list is used or implied. The default is to use a pager. See git-config[1].

Warning

Missing zh_HANS-CN/includes/cmd-config-section-rest.txt

See original version for this content.

Warning

Missing zh_HANS-CN/config/branch.txt

See original version for this content.

实例

从一个已知的标签开始开发
$ 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. Delete the remote-tracking branches "todo", "html" and "man". The next fetch or pull will create them again unless you configure them not to. See git-fetch[1].

  2. 删除 "测试 "分支,即使 "主 "分支(或当前签出的任何一个分支)没有测试分支的所有提交。

从一个特定的远端列出分支
$ git branch -r -l '<远程仓库>/<模式>'                 (1)
$ git for-each-ref 'refs/remotes/<远程仓库>/<模式>'    (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>被重新编译或修改时需要特别关注的分支,因为这些分支包含指定的<commit>。

  • `--no-contains <commit>`是其反义词,即不包含指定<commit>的分支。

  • `--merged`用于查找所有可以安全删除的分支,因为这些分支被HEAD完全包含。

  • `--no-merged`是用来寻找可以合并到HEAD的候选分支,因为这些分支没有被HEAD完全包含。

当组合多个 --contains--no-contains 过滤器时,只显示至少包含一个 --contains 的提交,并且不包含 --no-contains 的提交引用。

当结合多个 --merged--no-merged 过滤器时,只显示至少有一个 --merged 提交和没有 --no-merged 提交的引用。

GIT

属于 git[1] 文档

scroll-to-top