極狐GitLab 分支管理功能介紹

極狐GitLab 是 GitLab 在中國的發行版，關于中文參考文檔和資料有：

極狐GitLab 中文文檔
極狐GitLab 中文論壇
極狐GitLab 官網

分支 (BASIC ALL)

分支是項目工作樹的一個版本。分支是項目開發的基礎。當你創建一個新的項目時，極狐GitLab 會為你的倉庫創建一個默認分支。默認分支設置可以在項目、子組、組或實例中配置。

隨著項目的增長，團隊會創建更多的分支。每個分支代表一組更改，這允許并行進行開發工作。一個分支中的開發工作不會影響另一個分支。

分支的開發工作流程是：

1.創建一個分支并向其添加提交。為了簡化這個過程，你應該遵循分支命名模式。
2.當工作準備好進行審查時，創建一個合并請求以提議將分支中的更改合并。
3.使用審查應用預覽更改。

4.請求審查。
5.在你的合并請求獲得批準后，將你的分支合并到源分支。合并請求的合并方法決定了項目中如何處理合并請求。
6.在分支內容合并后，刪除已合并的分支。

查看所有分支

要在極狐GitLab 用戶界面中查看和管理分支：

1.在左側邊欄中，選擇 搜索或轉到 并找到你的項目。
2.在左側邊欄中，選擇 代碼 > 分支。

在此頁面，你可以：

查看所有分支，或篩選以僅查看活躍或過時的分支。
如果在過去三個月內對分支進行了提交，則該分支被視為活躍分支。否則，它被視為過時分支。
創建新分支。
比較分支。
刪除已合并的分支。
查看指向默認分支的合并請求鏈接。
指向非默認分支的合并請求的分支會顯示 {merge-request} 新建 合并請求按鈕。
查看分支規則。
查看分支的最新流水線狀態。

創建分支

在極狐GitLab UI 中創建新分支

前提條件：

你必須至少擁有項目的開發者角色。

要從極狐GitLab UI 創建新分支：

1.在左側邊欄中，選擇 搜索或轉到 并找到你的項目。
2.選擇 代碼 > 分支。
3.在右上角，選擇 新建分支。
4.輸入 分支名稱。
5.在 創建自 中，選擇分支的基礎：現有分支、現有標簽或提交 SHA。
6.選擇 創建分支。

在空白項目中

一個空白項目不包含分支，但你可以添加一個。

前提條件：

你必須至少擁有項目的開發者角色。
如果你沒有維護者或所有者角色，默認分支保護必須設置為部分保護或不保護，以便你可以向默認分支推送提交。

要向空白項目添加默認分支：

1.在左側邊欄中，選擇 搜索或轉到 并找到你的項目。
2.滾動到 此項目的存儲庫為空 并選擇你想要添加的文件類型。
3.在 Web IDE 中，對該文件進行任何所需的更改，然后選擇創建提交。
4.輸入提交消息，然后選擇提交。

極狐GitLab 會創建一個默認分支并將你的文件添加到其中。

從議題創建分支

在查看議題時，你可以直接從該頁面創建關聯的分支。以這種方式創建的分支使用從議題中創建分支的默認命名模式，包括變量。

前提條件：

你必須至少擁有項目的開發者角色。

要從議題中創建分支：

1.在左側邊欄中，選擇 搜索或轉到 并找到你的項目。
2.選擇 計劃 > 議題 并找到你的議題。
3.在議題描述下方，找到 創建合并請求 下拉列表，并選擇 {chevron-down} 以顯示下拉列表。
4.選擇 創建分支。根據項目的默認命名模式，提供了一個默認的 分支名稱。如果需要，輸入不同的 分支名稱。
5.選擇 創建分支 以基于項目的默認分支創建分支。

命名您的分支

Git 強制執行分支命名規則，以確保分支名稱與其他工具兼容。極狐GitLab 增加了額外的分支命名要求，并為結構良好的分支名稱提供了額外的好處。

極狐GitLab 對所有分支強制執行以下額外規則：

分支名稱中不允許有空格。
禁止使用包含 40 個十六進制字符的分支名稱，因為它們與 Git 提交哈希值相似。
分支名稱區分大小寫。

常見的軟件包（如 Docker）可能會強制執行額外的分支命名限制。

為了與其他軟件包保持最佳兼容性，請僅使用：

數字
連字符 (-)
下劃線 (_)
ASCII 標準表中的小寫字母

你可以在分支名稱中使用正斜杠 (/) 和表情符號，但不能保證與其他軟件包的兼容性。

具有特定格式的分支名稱提供額外的好處：

通過在分支名稱前加上議題編號簡化合并請求工作流程。
根據分支名稱自動化分支保護。
在將分支推送到 GitLab 之前，使用推送規則測試分支名稱。
定義在合并請求上運行的CI/CD 作業。

配置從議題創建分支的默認模式

默認情況下，極狐GitLab 在從議題創建分支時使用模式 %{id}-%{title}，但你可以更改此模式。

前提條件：

你必須至少擁有項目的維護者角色。

要更改從議題創建分支的默認模式：

1.在左側邊欄中，選擇 搜索或轉到 并找到你的項目。
2.選擇 設置 > 倉庫。
3.展開 分支默認值。
4.滾動到 分支名稱模板并輸入一個值。該字段支持以下變量：

%{id}：議題的數字 ID。
%{title}：議題的標題，修改為僅使用 Git 分支名稱中可接受的字符。

5.選擇 保存更改。

在分支名稱前加上議題編號

為了簡化合并請求的創建，請以議題編號開頭命名 Git 分支名稱，后跟連字符。

例如，要將分支鏈接到議題 #123，請以 123- 開頭命名分支。
議題和分支必須在同一個項目中。

極狐GitLab 使用議題編號將數據導入合并請求：

議題被標記為與合并請求相關。議題和合并請求顯示相互鏈接。
分支連接到議題。
如果你的項目配置了默認關閉模式，合并合并請求時也會關閉相關議題。
如果合并請求在同一個項目中，而不是一個分叉，議題的里程碑和標簽會被復制到合并請求中。

管理和保護分支

極狐GitLab 提供多種方法來保護各個分支。這些方法確保您的分支從創建到刪除都能得到監督和質量檢查。要查看和編輯分支保護，請參閱分支規則。

比較分支

要比較存儲庫中的分支：

1.在左側邊欄中，選擇 搜索或轉到 并找到你的項目。
2.選擇 代碼 > 比較修訂。
3.選擇源分支以搜索所需的分支。精確匹配優先顯示。您可以使用以下運算符來優化搜索：

^ 匹配分支名稱的開頭：^feat 匹配 feat/user-authentication。
$ 匹配分支名稱的結尾：widget$ 匹配 feat/search-box-widget。
*使用通配符匹配：branch*cache* 匹配 fix/branch-search-cache-expiration。
您可以組合運算符：^chore/*migration$ 匹配 chore/user-data-migration。

4.選擇目標存儲庫和分支。精確匹配優先顯示。
5.在 顯示更改 下，選擇比較分支的方法：

僅顯示源分支的傳入更改（默認）顯示自兩個分支的最新共同提交以來源分支的差異。它不包括源分支創建后對目標分支進行的無關更改。此方法使用 git diff <from>...<to> Git 命令。為了比較分支，此方法使用合并基而不是實際提交，因此從 cherry-pick 的提交中更改會顯示為新更改。
包括源分支創建以來對目標分支的更改顯示兩個分支之間的所有差異。此方法使用 git diff <from> <to> Git 命令。

6.選擇比較以顯示提交列表和更改的文件。
7.可選。要反轉源和目標，選擇 交換修訂（{substitute}）。

刪除已合并的分支

如果已合并的分支滿足以下所有條件，則可以批量刪除：

它們不是受保護的分支。
它們已合并到項目的默認分支。

前提條件：

您必須至少擁有項目的開發者角色。

操作步驟：

1.在左側邊欄中，選擇 搜索或轉到 并找到你的項目。
2.選擇 代碼 > 分支。
3.在頁面右上角，選擇 更多 {ellipsis_v}。
4.選擇 刪除已合并的分支。
5.在對話框中，輸入單詞 delete 以確認，然后選擇 刪除已合并的分支。

注意：刪除分支不會完全擦除所有相關數據。某些信息會保留以維護項目歷史記錄并支持恢復過程。有關更多信息，請參閱處理敏感信息。

為目標分支配置工作流 (PREMIUM ALL)

在 GitLab 16.4 中引入，帶有名為 target_branch_rules_flag 的標志。默認啟用。

在 GitLab 16.7 中移除功能標志。

一些項目使用多個長期分支進行開發，如 develop 和 qa。
在這些項目中，你可能希望將 main 保持為默認分支，但希望合并請求目標指向 develop 或 qa。目標分支工作流有助于確保合并請求針對項目的適當開發分支。

當你創建合并請求時，工作流會檢查分支名稱。如果分支名稱與工作流匹配，合并請求將針對你指定的分支。如果分支名稱不匹配，合并請求將針對項目的默認分支。

規則按“首次匹配”原則處理 - 如果兩個規則匹配同一個分支名稱，則應用最上面的規則。

前提條件：

你必須至少擁有維護者角色。

要創建目標分支工作流：

1.在左側邊欄中，選擇 搜索或轉到 并找到你的項目。
2.選擇 設置 > 合并請求。
3.向下滾動到 合并請求分支工作流
4.選擇 添加分支目標。
5.對于 分支名稱模式，提供一個字符串或通配符以與分支名稱進行比較。
6.選擇 目標分支，當分支名稱與 分支名稱模式 匹配時使用。
7.選擇保存。

目標分支工作流示例

你可以將項目配置為具有以下目標分支工作流：

分支名稱模式	目標分支
`feature/*`	`develop`
`bug/*`	`develop`
`release/*`	`main`

這些目標分支簡化了為項目創建合并請求的過程，該項目：

使用 main 表示應用程序的已部署狀態。
在另一個長期運行的分支（如 develop）中跟蹤當前未發布的開發工作。

如果你的工作流最初將新功能放在 develop 而不是 main 中，這些目標分支確保所有匹配 feature/* 或 bug/* 的分支不會錯誤地針對 main。
當你準備發布到 main 時，創建一個名為 release/* 的分支，并確保該分支針對 main。

刪除目標分支工作流

當你刪除目標分支工作流時，現有的合并請求保持不變。
前提條件：

你必須至少擁有維護者角色。

操作步驟：

1.在左側邊欄中，選擇搜索或轉到并找到你的項目。
2.選擇設置 > 合并請求。
3.在你要刪除的分支目標上選擇刪除。

故障排除

包含相同提交的多個分支
從更深的技術層面來看，Git 分支不是獨立的實體，而是附加到一組提交 SHA 的標簽。當極狐GitLab 確定分支是否已合并時，它會檢查目標分支是否存在這些提交 SHA。
這種行為可能會在兩個合并請求包含相同提交時導致意外結果。在此示例中，分支 B 和 C 都從分支 A 的相同提交 (3) 開始：
在這里插入圖片描述

如果你合并分支 B，分支 A 也會顯示為已合并（無需任何操作），因為分支 A 的所有提交現在都出現在目標分支 main 中。分支 C 仍然未合并，因為提交 5 不是分支 A 或 B 的一部分。

合并請求 A 保持合并狀態，即使你嘗試將新提交推送到其分支。如果合并請求 A 中的任何更改未合并（因為它們不是合并請求 A 的一部分），請為它們打開一個新的合并請求。

錯誤：存在歧義的 `HEAD` 分支

在 2.16.0 之前的 Git 版本中，你可以創建一個名為 HEAD 的分支。
這個名為 HEAD 的分支與 Git 用于描述活動（已檢出）分支的內部引用（也名為 HEAD）發生沖突。此命名沖突可能會阻止你更新存儲庫的默認分支：

Error: Could not set the default branch. Do you have a branch named 'HEAD' in your repository?

要解決此問題：

1.在左側邊欄中，選擇 搜索或轉到 并找到你的項目。
2.選擇 代碼 > 分支。
3.搜索名為 HEAD 的分支。
4.確保該分支沒有未提交的更改。
5.選擇 刪除分支，然后選擇是，刪除分支。

Git 版本 2.16.0 及更高版本，防止你創建具有此名稱的分支。

查找你創建的所有分支

要在項目中查找你創建的所有分支，請在 Git 存儲庫中運行此命令：

git for-each-ref --format='%(authoremail) %(refname:short)' | grep $(git config --get user.email)

要獲取項目中所有分支的總數，并按作者排序，請在 Git 存儲庫中運行此命令：

git for-each-ref --format='%(authoremail)'  | sort | uniq -c | sort -g

錯誤：`Failed to create branch 4:Deadline Exceeded`

此錯誤是由 Gitaly 中的超時引起的。當創建分支所需時間超過配置的超時時間時，會發生此錯誤。
要解決此問題，請選擇以下方法之一：

禁用耗時的服務器鉤子。請參閱 Git 服務器鉤子。
增加 Gitaly 的超時設置。請參閱 Gitaly 超時。