簡體中文 ▾ 主題 ▾ 最新版本 ▾ 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>。特殊情況下，對於 <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

刪除一個分支。該分支必須已完全合併到其上游分支，或者合併到 HEAD（如果未使用 --track 或 --set-upstream-to 設定上游）。

-D

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

--create-reflog

建立分支的 reflog。這會啟用對分支 ref 所做的所有更改的記錄，從而能夠使用基於日期的 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）。

請注意，git branch -f <branch-name> [<start-point>]，即使帶有 -f，也會拒絕更改同一個倉庫連結的另一個工作樹中已簽出的現有分支 <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 的行為是僅當開始點是遠端跟蹤分支且新分支的名稱與遠端分支的名稱相同時，給出 --track=direct。

有關 branch.<name>.remote 和 branch.<name>.merge 選項如何使用的更多討論，請參閱 git-pull[1] 和 git-config[1]。

--no-track

不要設定“上游”配置，即使 branch.autoSetupMerge 配置變數已設定。

--recurse-submodules

此選項是實驗性的！如果啟用了 submodule.propagateBranches，則導致當前命令遞迴到子模組。請參閱 submodule.propagateBranches 在 git-config[1] 中。目前僅支援分支建立。

在建立分支時，將在父專案及其所有子模組的 <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>

一個字串，用於內插顯示的分支 ref 和其指向的物件中的 %(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 以進行推送。它還覆蓋 remote.pushDefault 以從分支 <name> 進行推送。當您從一個地方（例如您的上游）拉取並推送到另一個地方（例如您自己的釋出儲存庫）時，您需要設定 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 給出的遠端獲取的 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，則在執行 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 或 amended，需要特別注意的所有分支，因為那些分支包含指定的 <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] 套件的一部分