Branches

Branches are versions of a project’s working tree. When you create a new project, GitLab creates a default branch (which cannot be deleted) for your repository. Default branch settings can be configured at the project, subgroup, group, or instance level.

As your project grows, your team creates more branches, preferably by following branch naming patterns. Each branch represents a set of changes, which allows development work to be done in parallel. Development work in one branch does not affect another branch.

Branches are the foundation of development in a project:

  1. To get started, create a branch and add commits to it.
  2. When the work is ready for review, create a merge request to propose merging the changes in your branch. To streamline this process, you should follow branch naming patterns.
  3. Preview changes in a branch with a review app.
  4. After the contents of your branch are merged, delete the merged branch.

Manage and protect branches

GitLab provides you multiple methods to protect individual branches. These methods ensure your branches receive oversight and quality checks from their creation to their deletion:

  • The default branch in your project receives extra protection.
  • Configure protected branches to restrict who can commit to a branch, merge other branches into it, or merge the branch itself into another branch.
  • Configure approval rules to set review requirements, including security-related approvals, before a branch can merge.
  • Integrate with third-party status checks to ensure your branch contents meet your standards of quality.

You can manage your branches:

View all branches

To view and manage your branches in the GitLab user interface:

  1. On the top bar, select Main menu > Projects and find your project.
  2. On the left sidebar, select Repository > Branches.

On this page, you can:

  • See all branches, active branches, or stale branches.
  • Create new branches.
  • Compare branches.
  • Delete merged branches.

View branches with configured protections

Version history
On self-managed GitLab, by default this feature is not available. To make it available, ask an administrator to enable the feature flag named branch_rules. On GitLab.com, this feature is available.

Branches in your repository can be protected in multiple ways. You can:

  • Limit who can push to the branch.
  • Limit who can merge the branch.
  • Require approval of all changes.
  • Require external tests to pass.

The Branch rules overview page shows all branches with any configured protections, and their protection methods:

Example of a branch with configured protections

Prerequisites:

  • You must have at least the Developer role in the project.

To view the Branch rules overview list:

  1. On the top bar, select Main menu > Projects and find your project.
  2. On the left sidebar, select Settings > Repository.
  3. Expand Branch Rules to view all branches with protections.
    • To add protections to a new branch:
      1. Select Add branch rule.
      2. Select Create protected branch.
    • To view more information about protections on an existing branch:
      1. Identify the branch you want more information about.
      2. Select Details to see information about its:

Prefix branch names with issue numbers

To streamline the creation of merge requests, start your branch name with an issue number. GitLab uses the issue number to import data into the merge request:

  • The issue is marked as related. The issue and merge request display links to each other.
  • If your project is configured with a default closing pattern, merging the merge request also closes the related issue.
  • The issue milestone and labels are copied to the merge request.

Compare branches

Version history
  • Repository filter search box introduced in GitLab 13.10.
  • Revision swapping introduced in GitLab 13.12.

To compare branches in a repository:

  1. On the top bar, select Main menu > Projects and find your project.
  2. On the left sidebar, select Repository > Compare revisions.
  3. Select the Source branch to search for your desired branch. Exact matches are shown first. You can refine your search with operators:
    • ^ matches the beginning of the branch name: ^feat matches feat/user-authentication.
    • $ matches the end of the branch name: widget$ matches feat/search-box-widget.
    • * matches using a wildcard: branch*cache* matches fix/branch-search-cache-expiration.
    • You can combine operators: ^chore/*migration$ matches chore/user-data-migration.
  4. Select the Target repository and branch. Exact matches are shown first.
  5. Select Compare to show the list of commits, and changed files. To reverse the Source and Target, select Swap revisions.

Delete merged branches

Delete merged branches

This feature allows merged branches to be deleted in bulk. Only branches that have been merged into the project’s default branch and are not protected are deleted as part of this operation.

It’s particularly useful to clean up old branches that were not deleted automatically when a merge request was merged.

Troubleshooting

Multiple branches containing the same commit

At a deeper technical level, Git branches aren’t separate entities, but labels attached to a set of commit SHAs. When GitLab determines whether or not a branch has been merged, it checks the target branch for the existence of those commit SHAs. This behavior can cause unexpected results when two merge requests contain the same commits. In this example, branches B and C both start from the same commit (3) on branch A:

gitGraph 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"

If you merge branch B, branch A also appears as merged (without any action from you) because all commits from branch A now appear in the target branch main. Branch C remains unmerged, because commit 5 wasn’t part of branch A or B.

Merge request A remains merged, even if you attempt to push new commits to its branch. If any changes in merge request A remain unmerged (because they weren’t part of merge request A), open a new merge request for them.

Error: ambiguous HEAD branch exists

In versions of Git earlier than 2.16.0, you could create a branch named HEAD. This branch named HEAD collides with the internal reference (also named HEAD) Git uses to describe the active (checked out) branch. This naming collision can prevent you from updating the default branch of your repository: 

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

To fix this problem:

  1. On the top bar, select Main menu > Projects and find your project.
  2. On the left sidebar, select Repository > Branches.
  3. Search for a branch named HEAD.
  4. Make sure the branch has no uncommitted changes.
  5. Select Delete branch, then Yes, delete branch.

Git versions 2.16.0 and later, prevent you from creating a branch with this name.