Git 設定上游分支

上游分支是本地分支所追蹤的遠端追蹤分支。設定好這項關係後，Git 就能推斷常見的 git pull 和 git push 操作要比較或使用哪個遠端分支。請依照遠端分支尚未發布、已經存在，或需要首次在本地簽出的情況，選擇適合的命令。

上游分支的作用

追蹤設定會將一個本地分支連結到一個遠端追蹤分支，例如本地的 my-feature-branch 對應到 origin/my-feature-branch。這項設定本身不會合併分支，也不會複製提交；它會提供 Git 預設的目的地和比較基準，因此之後執行 git pull 和 git push 時，通常可以省略遠端和分支參數。

需要參照遠端追蹤分支的命令，要求該分支已存在於你的本地儲存庫中。從遠端擷取資料時，遠端追蹤分支會隨之更新。以下範例以 origin 為遠端名稱、my-feature-branch 為分支名稱；請替換成你儲存庫中的名稱。

推送新分支時設定上游

如果本地分支尚未發布，可以執行 git push origin my-feature-branch 推送分支，但不設定追蹤關係。這會將分支推送到 origin，之後推送時仍須指定遠端和分支。若要在同一個操作中發布分支並設定追蹤，請執行 git push --set-upstream origin my-feature-branch；-u 是較短的等效寫法。設定追蹤後，之後推送通常可以省略遠端和分支參數。

小型格式器可以協助確認參數順序。它會輸出供你執行的命令，但不會呼叫 Git，也不會發布分支。

執行以下範例：

本節中的程式碼以及顯示的標籤或輸出仍為英文。

branch = "my-feature-branch"
remote = "origin"
print(f"git push --set-upstream {remote} {branch}")

程式碼範例輸出的 Git 命令維持英文，方便你直接複製到終端機執行。

git push --set-upstream origin my-feature-branch

在你的儲存庫中執行 Git 命令後，遠端分支就會建立，而目前的本地分支也會追蹤該分支。--set-upstream-to 選項屬於 git branch；它不是發布新分支時使用的 git push 選項。

為現有本地分支設定上游

如果本地分支和它的遠端追蹤分支都已存在，請切換到該本地分支，再用 git branch --set-upstream-to=origin/my-feature-branch 設定上游。簡寫是 git branch -u origin/my-feature-branch。

這兩種寫法都會設定目前所在的本地分支。請先確認自己位於要連結的分支，例如執行 git checkout my-feature-branch；如果 origin/my-feature-branch 尚未出現在遠端追蹤參照中，請先從遠端擷取資料。這項設定只會變更分支關係，不會推送提交。

建立追蹤遠端分支的本地分支

如果遠端已有該分支，但你的本地儲存庫尚未有此分支，可以使用 git checkout -b my-feature-branch origin/my-feature-branch，從遠端追蹤分支建立並切換到本地分支。這種常用的簽出寫法會建立本地分支，並將指定的遠端追蹤分支設為它的上游。

本地名稱不能已經被使用，而且遠端追蹤參照必須可用；若有需要，請先從遠端擷取資料。這和發布新的本地分支不同：在這個情境中，遠端分支是本地分支的起點。

檢查或移除上游分支

在本地分支上執行 git status，即可檢查它與上游的關係。當 Git 能比較兩邊的狀態時，輸出可能會指出分支領先、落後或已分歧，協助你決定要推送、擷取或整合提交。如果狀態沒有顯示追蹤資訊，請確認已設定上游，並且已擷取遠端追蹤參照。

若要停止追蹤遠端分支，請在本地分支上執行 git branch --unset-upstream。這只會移除追蹤關係，不會刪除本地分支、遠端分支或提交。之後可以用 git branch --set-upstream-to=<remote>/<branch> 設定其他上游。