ブランチ

ブランチは、チームの開発作業を整理し、分離します。複数のメンバーが異なる機能に同時に取り組む際に、ブランチによって変更が相互に競合するのを防ぎます。それぞれのブランチは、新しい機能を実装したり、バグを修正したり、アイデアを試したりできる、独立したワークスペースとして機能します。

ブランチを使用すると、チームは次のことができるようになります:

• メインコードベースを中断することなく、個別の機能に取り組む。
• プロジェクトの他の部分に影響を与える前に、提案された変更をレビューする。
• 他の作業に影響を与えることなく、問題のある変更をロールバックする。
• 制御された予測可能な方法で、本番環境に変更をデプロイする。

ブランチの開発ワークフローは次のとおりです:

1. ブランチを作成し、コミットを追加します。このプロセスを効率化するには、ブランチの命名パターンに従う必要があります。
2. 作業のレビューを行う準備ができたら、ブランチの変更のマージを提案するマージリクエストを作成します。
3. レビューアプリで変更をプレビューします。
4. レビューをリクエストします。
5. マージリクエストが承認されたら、ブランチをoriginブランチにマージします。マージ方法は、プロジェクトでのマージリクエストの処理方法を決定します。
6. ブランチの内容がマージされたら、マージ済みブランチを削除します。

すべてのブランチを表示する

GitLab UIでブランチを表示および管理するには、以下を実行します:

1. 左側のサイドバーで、検索または移動先を選択して、プロジェクトを見つけます。
2. 左側のサイドバーで、コード > ブランチを選択します。

このページでは、以下のことができます:

• すべてのブランチを表示する、または、フィルタリングしてアクティブなブランチや古いブランチのみを表示する。

  過去3か月以内にコミットが行われた場合、ブランチはアクティブであると見なされます。それ以外の場合は、古いブランチと見なされます。

• 新しいブランチを作成する。

• マージ済みブランチを削除する。

• デフォルトブランチを指すマージリクエストのリンクを表示する。

  デフォルトブランチを指していないマージリクエストを含むブランチには、 新しいマージリクエストボタンが表示されます。

• ブランチルールを表示する。

• ブランチの最新のパイプラインの状態を表示する。

ブランチを作成する

前提要件:

• プロジェクトのデベロッパーロール以上が必要です。

GitLab UIから新しいブランチを作成するには、以下を実行します:

1. 左側のサイドバーで、検索または移動先を選択して、プロジェクトを見つけます。
2. コード > ブランチを選択します。
3. 右上隅で、新しいブランチを選択します。
4. ブランチ名を入力します。
5. 作成元で、ブランチのベースを選択します。
6. ブランチを作成を選択します。

空のプロジェクトで作成する

空のプロジェクトにはブランチが含まれていませんが、追加することができます。

前提要件:

• プロジェクトのデベロッパーロール以上が必要です。
• メンテナーまたはオーナーのロールを持っていない場合、コミットをデフォルトブランチにプッシュするには、デフォルトブランチの保護をPartially protectedまたはNot protectedに設定する必要があります。

デフォルトブランチを空のプロジェクトに追加するには、以下を実行します:

1. 左側のサイドバーで、検索または移動先を選択して、プロジェクトを見つけます。
2. このプロジェクトのリポジトリは空ですまでスクロールして、追加するファイルのタイプを選択します。
3. Web IDEで、このファイルに必要な変更を加えたら、コミットを作成を選択します。
4. コミットメッセージを入力し、コミットを選択します。

GitLabはデフォルトブランチを作成し、そこにファイルを追加します。

イシューから作成する

イシューを表示すると、そのページから直接、関連付けられたブランチを作成できます。この方法で作成されたブランチは、変数を含むイシューからのブランチ名のデフォルトパターンを使用します。

前提要件:

• プロジェクトのデベロッパーロール以上が必要です。

イシューからブランチを作成するには、以下を実行します:

1. 左側のサイドバーで、検索または移動先を選択して、プロジェクトを見つけます。
2. Plan > イシューを選択して、イシューを見つけます。
3. イシューの説明の下で、マージリクエストを作成 を選択して、ドロップダウンリストを表示します。
4. ブランチを作成を選択します。
5. ダイアログで、**ソース (ブランチまたはタグ)**ドロップダウンリストから、ソースブランチまたはタグを選択します。
6. 提案されたブランチ名をレビューします。これはプロジェクトのブランチ名のデフォルトパターンに基づいています。
7. オプション。別のブランチ名を使用する必要がある場合は、ブランチ名テキストボックスに入力します。
8. ブランチを作成を選択します。

空のリポジトリでブランチを作成する方法については、空のリポジトリの動作を参照してください。

作成済みのブランチの名前のプレフィックスがイシュー番号である場合、GitLabはイシューに関連するマージリクエストをクロスリンクします。

タスクから作成する

前提要件:

• プロジェクトのデベロッパーロール以上が必要です。

タスクから直接ブランチを作成するには、以下を実行します:

1. 左側のサイドバーで、検索または移動先を選択して、プロジェクトを見つけます。
2. Plan > イシューを選択します。
3. イシューリストで、タスクを見つけます。
4. タスクの説明の下で、マージリクエストを作成 を選択し、ドロップダウンリストを表示します。
5. ブランチを作成を選択します。
6. ダイアログで、Source branch or tag（ソース（ブランチまたはタグ））ドロップダウンリストから、ソースブランチまたはタグを選択します。
7. 提案されたブランチ名をレビューします。これはプロジェクトのブランチ名のデフォルトパターンに基づいています。
8. オプション。別のブランチ名を使用する必要がある場合は、ブランチ名テキストボックスに入力します。
9. ブランチを作成を選択します。

空のリポジトリでブランチを作成する方法については、空のリポジトリの動作を参照してください。

作成済みのブランチの名前のプレフィックスがタスク番号である場合、GitLabはイシューと関連するマージリクエストをクロスリンクします。

空のリポジトリの動作

Gitリポジトリが空の場合、GitLabは以下を実行します:

• デフォルトブランチを作成します。
• 空白のREADME.mdファイルをコミットします。
• イシューのタイトルに基づいて新規のブランチを作成し、リダイレクトします。
• プロジェクトがKubernetesなどのデプロイサービスで設定されている場合、GitLabは.gitlab-ci.ymlファイル作成を支援し、自動デプロイを設定するよう求めるプロンプトを表示します。

ブランチに名前を付ける

Gitはブランチ名のルールを適用して、ブランチ名が他のツールとの互換性を維持できるようにします。GitLabはブランチ名に追加の要件を設定し、構造化されたブランチ名に対してメリットを提供します。

GitLabでは、すべてのブランチに以下の追加ルールを適用します:

• ブランチ名にはスペースを使用できません。
• 40桁の16進数のブランチ名は、Gitのコミットハッシュと似ているため禁止されています。
• ブランチ名では、大文字と小文字が区別されます。

Dockerなどの一般的なソフトウェアパッケージでは、追加のブランチ命名制限を適用できます。

他のソフトウェアパッケージとの最適な互換性を得るため、以下のみを使用してください:

• 数字
• ハイフン（-）
• アンダースコア（_）
• ASCII標準コード表の小文字

ブランチ名にはスラッシュ（/）と絵文字を使用できますが、他のソフトウェアパッケージとの互換性は保証されません。

特定のフォーマットのブランチ名を使用すると、次のような追加の利点を得られます:

• ブランチ名のプレフィックスをイシュー番号にすることで、マージリクエストワークフローを効率化できます。
• ブランチ名に基づいてブランチ保護を自動化します。
• ブランチがGitLabにプッシュされる前に、プッシュルールでブランチ名をテストします。
• マージリクエストで実行するCI/CDジョブを定義します。

イシューからのブランチ名のデフォルトパターンを設定する

デフォルトでは、GitLabはイシューからブランチを作成する場合に%{id}-%{title}というパターンを使用しますが、このパターンは変更できます。

前提要件:

• プロジェクトのメンテナーロール以上が必要です。

イシューから作成されたブランチのデフォルトパターンを変更するには、以下を実行します:

1. 左側のサイドバーで、検索または移動先を選択して、プロジェクトを見つけます。
2. 設定 > リポジトリを選択します。
3. ブランチのデフォルトを展開します。
4. ブランチ名のテンプレートまでスクロールし、値を入力します。このフィールドは次の変数をサポートしています:
   • %{id}: イシューの数値ID。
   • %{title}: Gitブランチ名で許容される文字のみを使用するように変更されたイシューのタイトル。
5. 変更を保存を選択します。

ブランチ名に番号のプレフィックスを付ける

マージリクエストの作成を効率化するには、Gitブランチ名をイシュー番号またはタスク番号で始め、その後にハイフンを付けます。たとえば、ブランチをイシュー#123にリンクするには、ブランチ名を123-で始めます。

ブランチは、イシューまたはタスクと同じプロジェクト内に存在する必要があります。

GitLabはこの番号を使用して、マージリクエストにデータをインポートします:

• アイテムはマージリクエストに関連付けられているものとしてマークされ、相互へのリンクが表示されます。
• ブランチはイシューまたはタスクに接続されています。
• プロジェクトにデフォルトのクローズパターンが設定されている場合、マージリクエストをマージすると、関連するイシューもクローズされます。
• マージリクエストが同じプロジェクト内にあり、フォークしていない場合、イシューのマイルストーンとラベルがマージリクエストにコピーされます。

ブランチを管理および保護する

GitLabは、個々のブランチを保護するための複数の方法を提供しています。これらの方法により、ブランチを作成してから削除するまで、監視と品質チェックを受けることができます。ブランチ保護を表示および編集するには、ブランチルールを参照してください。

ブランチの比較をダウンロード

GitLabの外部で使用するために、ブランチ間の比較をdiffまたはパッチファイルとしてダウンロードできます。

差分として

ブランチの比較をdiffとしてダウンロードするには、比較URLにformat=diffを追加します:

• URLにクエリパラメータがない場合は、?format=diffを追加します:

  https://gitlab.example.com/my-group/my-project/-/compare/main...feature-branch?format=diff

• URLにクエリパラメータが既にある場合は、&format=diffを追加します:

  https://gitlab.example.com/my-group/my-project/-/compare/main...feature-branch?from_project_id=2&format=diff

diffをダウンロードして適用するには、次の手順に従います:

curl "https://gitlab.example.com/my-group/my-project/-/compare/main...feature-branch?format=diff" | git apply

パッチファイルとして

ブランチの比較をパッチファイルとしてダウンロードするには、比較URLにformat=patchを追加します:

• URLにクエリパラメータがない場合は、?format=patchを追加します:

  https://gitlab.example.com/my-group/my-project/-/compare/main...feature-branch?format=patch

• URLにクエリパラメータが既にある場合は、&format=patchを追加します:

  https://gitlab.example.com/my-group/my-project/-/compare/main...feature-branch?from_project_id=2&format=patch

git amを使用してパッチをダウンロードして適用するには、次の手順に従います:

# Download and preview the patch
curl "https://gitlab.example.com/my-group/my-project/-/compare/main...feature-branch?format=patch" > changes.patch
git apply --check changes.patch

# Apply the patch
git am changes.patch

単一のコマンドでパッチをダウンロードして適用することもできます:

curl "https://gitlab.example.com/my-group/my-project/-/compare/main...feature-branch?format=patch" | git am

マージ済みブランチを削除する

マージされたブランチは、次のすべての要件を満たす場合に一括で削除できます:

• 保護ブランチではない。
• プロジェクトのデフォルトブランチにマージされている。

前提要件:

• プロジェクトのデベロッパーロール以上を持っている必要があります。

これを行うには、次の手順を実行します:

1. 左側のサイドバーで、検索または移動先を選択して、プロジェクトを見つけます。
2. コード > ブランチを選択します。
3. ページの右上隅で、More（詳細） を選択します。
4. マージされたブランチを削除を選択します。
5. ダイアログで、deleteと入力して確認し、マージされたブランチを削除を選択します。

ターゲットブランチのワークフローを設定する

一部のプロジェクトでは、developやqaなど、複数の長期ブランチを開発に使用します。これらのプロジェクトでは、mainをデフォルトのブランチとして保持し、代わりにマージリクエストのターゲットをdevelopまたはqaにすることがあります。ターゲットブランチのワークフローは、マージリクエストがプロジェクトに適した開発ブランチをターゲットとする際に役立ちます。

マージリクエストを作成すると、ワークフローはブランチの名前をチェックします。ブランチ名がワークフローと一致する場合、マージリクエストは指定されたブランチをターゲットとします。ブランチ名が一致しない場合、マージリクエストはプロジェクトのデフォルトブランチをターゲットとします。

ルールは「最初の一致」の基準で処理されます。2つのルールが同じブランチ名に一致する場合、最上位のルールが適用されます。

前提要件:

• メンテナーロール以上が必要です。

ターゲットブランチワークフローを作成するには、以下を実行します:

1. 左側のサイドバーで、検索または移動先を選択して、プロジェクトを見つけます。
2. 設定 > マージリクエストを選択します。
3. マージリクエストブランチのワークフローまでスクロールします。
4. ブランチターゲットを追加を選択します。
5. ブランチ名のパターンに、ブランチ名と照合する文字列またはワイルドカードを指定します。
6. ブランチ名がブランチ名のパターンと一致した場合に使用するターゲットブランチを選択します。
7. 保存を選択します。

ターゲットブランチワークフローの例

プロジェクトで、次のターゲットブランチワークフローを設定できます:

これらのターゲットブランチにより、次のようなプロジェクトのマージリクエストの作成プロセスを簡素化できます:

• mainを使用して、アプリケーションのデプロイ済みの状態を表す。
• developなど、別の長期運用ブランチで、現在未リリースの開発作業を追跡する。

ワークフローで、新しい機能を最初にmainではなくdevelopに配置する場合、これらのターゲットブランチにより、feature/*またはbug/*に一致するすべてのブランチが誤ってmainをターゲットにするのを防ぐことができます。

mainにリリースする準備ができたら、release/*という名前のブランチを作成し、このブランチがmainをターゲットにしていることを確認します。

ターゲットブランチワークフローを削除する

ターゲットブランチワークフローを削除しても、既存のマージリクエストは変更されません。

前提要件:

• メンテナーロール以上が必要です。

これを行うには、以下を実行します:

1. 左側のサイドバーで、検索または移動先を選択して、プロジェクトを見つけます。
2. 設定 > マージリクエストを選択します。
3. 削除するブランチターゲットで、削除を選択します。

関連トピック

• 保護ブランチ
• ブランチルール
• リビジョンを比較する
• マージリクエストの変更
• マージリクエストの変更をダウンロード
• ブランチAPI
• 保護ブランチAPI
• Git入門
• ブランチの概要

トラブルシューティング

同じコミットを含む複数のブランチ

より深い技術レベルでは、Gitブランチは個別のエンティティではなく、コミットSHAのセットにアタッチされたラベルです。GitLabは、ブランチがマージされたかどうかを判断する際に、ターゲットブランチにこれらのコミットSHAがあるかどうかを確認します。この動作は、2つのマージリクエストに同じコミットが含まれている場合に、予期せぬ結果を招く可能性があります。この例では、ブランチBとCはどちらも、ブランチAの同じコミット（3）から始まります:

%%{init: { "fontFamily": "GitLab Sans" }}%%
gitGraph
    accTitle: Diagram of multiple branches with the same commit
    accDescr: Branches A and B contain the same commit, but branch B also contains other commits. Merging branch B makes branch A appear as merged, because all its commits are merged.
    commit id:"a"
    branch "branch A"
    commit id:"b"
    commit id:"c" type: HIGHLIGHT
    branch "branch B"
    commit id:"d"
    checkout "branch A"
    branch "branch C"
    commit id:"e"
    checkout main
    merge "branch B" id:"merges commits b, c, d"

ブランチBをマージすると、ブランチAからのすべてのコミットがターゲットブランチmainに表示されるため、（何もアクションを起こさなくても）ブランチAもマージされたように見えます。コミット5がブランチAやBの一部ではなかったため、ブランチCはマージされていないままです。

マージリクエストAは、そのブランチに新しいコミットをプッシュしようとしても、マージされたままになります。マージリクエストAの変更がマージされていない場合（マージリクエストAの一部ではなかったため）、その変更のために新しいマージリクエストを開いてください。

エラー: あいまいなHEADブランチが存在します

Git 2.16.0より以前のバージョンでは、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のタイムアウトが原因で発生します。これは、ブランチの作成にかかる時間が、設定されたタイムアウト期間よりも長くなった場合に発生します。

この問題を解決するには、次のいずれかの方法を選択します:

• 時間のかかるサーバーフックを無効にします。
• Gitalyのタイムアウト設定を長くします。