Git
英文 ▾ 主題 ▾ 最新版本 ▾ 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

當格式化後的參照（refs）展開為空字串時，不要列印換行符號。

--column[=<選項>]
--no-column

以欄位顯示分支列表。選項語法請參閱配置變數 column.branch。不帶選項的 --column 和 --no-column 分別等同於 *always* 和 *never*。

此選項僅適用於非詳細模式。

-r
--remotes

列出或刪除（若與 -d 一起使用）遠端追蹤分支。與 --list 組合以匹配可選的模式。

-a
--all

列出遠端追蹤分支和本地分支。與 --list 組合以匹配可選的模式。

-l
--list

列出分支。使用可選的 <模式>...，例如 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 <上游>
--set-upstream-to=<上游>

設定 <branchname> 的追蹤資訊，以便將 <上游> 視為 <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。

<分支名稱>

要建立或刪除的分支名稱。新的分支名稱必須通過 git-check-ref-format[1] 定義的所有檢查。其中一些檢查可能會限制分支名稱中允許的字元。

<起始點>

新的分支頭將指向此提交。它可以給定為分支名稱、提交 ID 或標籤。如果省略此選項，則將改為使用目前的 HEAD。

<舊分支>

現有分支的名稱。如果省略此選項，則將改為使用目前分支的名稱。

<新分支>

現有分支的新名稱。與 <branchname> 相同的限制適用。

--sort=<鍵>

根據給定的鍵排序。在值之前加上 - 以降序排序。您可以多次使用 --sort=<鍵> 選項，在這種情況下，最後一個鍵將成為主鍵。支援的鍵與 git for-each-ref 中的鍵相同。排序順序預設為 branch.sort 變數配置的值（如果存在），或根據完整的參照名稱（包括 refs/... 前綴）排序。這會先列出分離的 HEAD（如果存在），然後是本機分支，最後是遠端追蹤分支。請參閱 git-config[1]。

--points-at <物件>

僅列出指定物件的分支。

--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 而不是合併（請參閱「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.<名稱>.pushRemote

當在 <名稱> 分支上時，此設定會覆寫用於推送的 branch.<名稱>.remote 設定。它也會覆寫從 <名稱> 分支推送時的 remote.pushDefault 設定。當您從一個位置（例如您的上游）拉取並推送到另一個位置（例如您自己的發布儲存庫）時，您會希望設定 remote.pushDefault 以指定所有分支要推送到的遠端，並使用此選項來覆寫特定分支的設定。

branch.<名稱>.merge

與 branch.<名稱>.remote 一起定義給定分支的上游分支。它會告知 git fetch/git pull/git rebase 要合併哪個分支，並且也可能會影響 git push (請參閱 push.default)。當在 <名稱> 分支中時，它會告知 git fetch 要在 FETCH_HEAD 中標記用於合併的預設 refspec。該值會被視為 refspec 的遠端部分，並且必須與從 "branch.<名稱>.remote" 給定的遠端所提取的 ref 相符。合併資訊會被 git pull (它會先呼叫 git fetch) 用來查詢要合併的預設分支。如果沒有此選項，git pull 預設會合併第一個提取的 refspec。指定多個值以進行章魚合併。如果您希望設定 git pull，以便從本機儲存庫中的另一個分支合併到 <名稱> 中，您可以將 branch.<名稱>.merge 指向所需的分支，並將相對路徑設定為 . (句點) 給 branch.<名稱>.remote。

branch.<名稱>.mergeOptions

設定合併到 <名稱> 分支的預設選項。語法和支援的選項與 git-merge[1] 的相同，但目前不支援包含空白字元的選項值。

branch.<名稱>.rebase

當為 true 時，在執行 "git pull" 時，會將 <名稱> 分支 rebase 到提取的分支之上，而不是合併預設遠端的預設分支。請參閱 "pull.rebase" 以非分支特定的方式執行此操作。

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

當值為 interactive (或簡寫為 i) 時，rebase 會以互動模式執行。

注意：這可能是一個危險的操作；除非您了解其含義，否則不要使用它 (詳情請參閱 git-rebase[1])。

branch.<名稱>.description

分支描述，可以使用 git branch --edit-description 編輯。分支描述會自動新增到 format-patch cover letter 或 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 會將 <遠端> 與您恰好以相同的 <遠端> 模式作為前綴的任何本機分支混淆。

  2. for-each-ref 可以採用各種選項。請參閱 git-for-each-ref[1]

模式通常需要引號。

注意事項

如果您正在建立一個想要立即切換到的分支，使用 "git switch" 命令及其 -c 選項可以更輕鬆地用單一命令完成相同的事情。

選項 --contains、--no-contains、--merged 和 --no-merged 服務於四個相關但不同的目的

  • --contains <提交> 用於尋找所有分支，如果 <提交> 要 rebase 或 amend，則這些分支需要特別注意，因為這些分支包含指定的 <提交>。

  • --no-contains <提交> 是其相反，即不包含指定的 <提交> 的分支。

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