8.6 KiB
stage | group | info | type |
---|---|---|---|
Create | Source Code | To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments | concepts, howto |
Default branch (FREE)
When you create a new project, GitLab creates a default branch in the repository. A default branch has special configuration options not shared by other branches:
- It's initially protected against accidental deletion and forced pushes.
- When a merge request uses an issue closing pattern to close an issue, the work is merged into this branch.
The name of your new project's default branch depends on any instance-level or group-level configuration changes made by your GitLab administrator. GitLab checks first for specific customizations, then checks at a broader level, using the GitLab default only if no customizations are set:
- A project-specific custom default branch name.
- A subgroup-level custom default branch name.
- A group-level custom default branch name.
- An instance-level custom default branch name. (FREE SELF)
- If no custom default branch name is set at any level, GitLab defaults to:
main
: Projects created with GitLab 14.0 or later.master
: Projects created before GitLab 14.0.
In the GitLab UI, you can change the defaults at any level. GitLab also provides the Git commands you need to update your copy of the repository.
Change the default branch name for a project
To update the default branch name for an individual project:
- Sign in to GitLab as a user with Administrator permissions.
- In the left navigation menu, go to Settings > Repository.
- Expand Default branch, and select a new default branch.
- (Optional) Select the Auto-close referenced issues on default branch check box to close issues when a merge request uses a closing pattern.
- Select Save changes.
API users can also use the default_branch
attribute of the
Projects API when creating or editing a project.
Change the default branch name for an instance or group
GitLab administrators can configure a new default branch name at the instance level or group level.
Instance-level custom initial branch name (FREE SELF)
- Introduced in GitLab 13.2.
- Feature flag removed in GitLab 13.12.
GitLab administrators of self-managed instances can customize the initial branch for projects hosted on that instance. Individual groups and subgroups can override this instance-wide setting for their projects.
- On the top bar, select Menu > {admin} Admin.
- In the left sidebar, select Settings > Repository.
- Expand Default initial branch name.
- Change the default initial branch to a custom name of your choice.
- Select Save changes.
Projects created on this instance after you change the setting use the custom branch name, unless a group-level or subgroup-level configuration overrides it.
Group-level custom initial branch name
- Introduced in GitLab 13.6.
Administrators of groups and subgroups can configure the default branch name for a group:
- Go to the group Settings > Repository.
- Expand Default initial branch name.
- Change the default initial branch to a custom name of your choice.
- Select Save changes.
Projects created in this group after you change the setting use the custom branch name, unless a subgroup configuration overrides it.
Update the default branch name in your repository
WARNING: Changing the name of your default branch can potentially break tests, CI/CD configuration, services, helper utilities, and any integrations your repository uses. Before you change this branch name, consult with your project owners and maintainers. Ensure they understand the scope of this change includes references to the old branch name in related code and scripts.
When changing the default branch name for an existing repository, you should preserve
the history of your default branch by renaming it, instead of deleting it. This example
renames a Git repository's (example
) default branch.
-
On your local command line, navigate to your
example
repository, and ensure you're on the default branch:cd example git checkout master
-
Rename the existing default branch to the new name (
main
). The argument-m
transfers all commit history to the new branch:git branch -m master main
-
Push the newly created
main
branch upstream, and set your local branch to track the remote branch with the same name:git push -u origin main
-
If you plan to remove the old default branch, update
HEAD
to point to your new default branch,main
:git symbolic-ref refs/remotes/origin/HEAD refs/remotes/origin/main
-
Sign in to GitLab as an administrator and follow the instructions to change the default branch for this project. Select
main
as your new default branch. -
Protect your new
main
branch as described in the protected branches documentation. -
(Optional) If you want to delete the old default branch:
-
Verify that nothing is pointing to it.
-
Delete the branch on the remote:
git push origin --delete master
You can delete the branch at a later time, after you confirm the new default branch is working as expected.
-
-
Notify your project contributors of this change, because they must also take some steps:
- Contributors should pull the new default branch to their local copy of the repository.
- Contributors with open merge requests that target the old default branch should manually
re-point the merge requests to use
main
instead.
-
In your repository, update any references to the old branch name in your code.
-
Update references to the old branch name in related code and scripts that reside outside your repository, such as helper utilities and integrations.
Default branch rename redirect
Introduced in GitLab 14.1
URLs for specific files or directories in a project embed the project's default branch name, and are often found in documentation or browser bookmarks. When you update the default branch name in your repository, these URLs change, and must be updated.
To ease the transition period, whenever the default branch for a project is changed, GitLab records the name of the old default branch. If that branch is deleted, attempts to view a file or directory on it are redirected to the current default branch, instead of displaying the "not found" page.
Resources
- Discussion of default branch renaming on the Git mailing list
- March 2021 blog post: The new Git default branch name
Troubleshooting
Unable to change default branch: resets to current branch
We are tracking this problem in issue 20474.
This issue often occurs when a branch named HEAD
is present in the repository.
To fix the problem:
-
In your local repository, create a new, temporary branch and push it:
git checkout -b tmp_default && git push -u origin tmp_default
-
In GitLab, proceed to change the default branch to that temporary branch.
-
From your local repository, delete the
HEAD
branch:git push -d origin HEAD
-
In GitLab, change the default branch to the one you intend to use.