簡體中文 ▾ 主題 ▾ 最新版本 ▾ git-branch 上次更新於 2.50.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）也適用相同規則。

請注意，即使使用 -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 變數配置的值（如果存在），否則基於完整的 refname（包括 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> 相同的限制適用。

配置

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 在 FETCH_HEAD 中標記為合併的預設 refspec。該值的處理方式類似於 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> rebase 到抓取的分支之上，而不是合併來自預設遠端倉庫的預設分支。有關以非分支特定方式執行此操作的詳細資訊，請參閱 pull.rebase。

當為 merges（或簡寫 m）時，將 --rebase-merges 選項傳遞給 git rebase，以便本地合併提交包含在 rebase 中（詳情請參閱 git-rebase[1]）。

當值為 interactive（或簡寫 i）時，rebase 以互動模式執行。

注意：這是一個可能危險的操作；除非您瞭解其影響，否則不要使用它（詳情請參閱 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. 刪除“test”分支，即使“master”分支（或當前檢出的任何分支）不包含來自 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]

模式通常需要加引號。

注意事項

如果您正在建立一個希望立即切換到的分支，使用 git switch 命令及其 -c 選項可以更輕鬆地透過一個命令完成相同的操作。

選項 --contains、--no-contains、--merged 和 --no-merged 有四個相關但不同的用途

  • --contains <commit> 用於查詢所有需要特別注意的分支，如果 <commit> 要進行 rebase 或修改，因為這些分支包含指定的 <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