diff options
Diffstat (limited to 'doc/user/project/repository/branches/default.md')
-rw-r--r-- | doc/user/project/repository/branches/default.md | 180 |
1 files changed, 180 insertions, 0 deletions
diff --git a/doc/user/project/repository/branches/default.md b/doc/user/project/repository/branches/default.md new file mode 100644 index 00000000000..1363d883e76 --- /dev/null +++ b/doc/user/project/repository/branches/default.md @@ -0,0 +1,180 @@ +--- +stage: Create +group: Source Code +info: "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" +type: concepts, howto +--- + +# Default branch + +When you create a new [project](../../index.md), GitLab creates a default branch +in the repository. A default branch has special configuration options not shared +by other branches: + +- It's [initially protected](../../protected_branches.md#protected-branches) against + accidental deletion and forced pushes. +- When a merge request uses an + [issue closing pattern](../../issues/managing_issues.md#closing-issues-automatically) + to close an issue, the work is merged into this branch. + +The name of your [new project's](../../index.md) 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: + +1. A [project-specific](#change-the-default-branch-name-for-a-project) custom default branch name. +1. A [subgroup-level](#group-level-custom-initial-branch-name) custom default branch name. +1. A [group-level](#group-level-custom-initial-branch-name) custom default branch name. +1. An [instance-level](#instance-level-custom-initial-branch-name) custom default branch name. **(FREE SELF)** +1. 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](#update-the-default-branch-name-in-your-repository) 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](../../index.md): + +1. Sign in to GitLab as a user with [Administrator](../../../permissions.md) permissions. +1. In the left navigation menu, go to **Settings > Repository**. +1. Expand **Default branch**, and select a new default branch. +1. (Optional) Select the **Auto-close referenced issues on default branch** check box to close + issues when a merge request + [uses a closing pattern](../../issues/managing_issues.md#closing-issues-automatically). +1. Select **Save changes**. + +API users can also use the `default_branch` attribute of the +[Projects API](../../../../api/projects.md) 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](#instance-level-custom-initial-branch-name) or +[group level](#group-level-custom-initial-branch-name). + +### Instance-level custom initial branch name **(FREE SELF)** + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/221013) in GitLab 13.2. +> - It's deployed behind a feature flag, enabled by default. +> - It cannot be enabled or disabled per-project. +> - It's recommended for production use. +> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#enable-or-disable-custom-initial-branch-name). + +GitLab [administrators](../../../permissions.md) 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. + +1. Go to **Admin Area > Settings > Repository**. +1. Expand **Default initial branch name**. +1. Change the default initial branch to a custom name of your choice. +1. 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. + +#### Enable or disable custom initial branch name **(FREE SELF)** + +Setting the default initial branch name is under development but ready for production use. +It is deployed behind a feature flag that is **enabled by default**. +[GitLab administrators with access to the GitLab Rails console](../../../../administration/feature_flags.md) +can opt to disable it for your instance. + +To disable it: + +```ruby +Feature.disable(:global_default_branch_name) +``` + +To enable it: + +```ruby +Feature.enable(:global_default_branch_name) +``` + +### Group-level custom initial branch name **(FREE)** + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/221014) in GitLab 13.6. + +Administrators of groups and subgroups can configure the default branch name for a group: + +1. Go to the group **Settings > Repository**. +1. Expand **Default initial branch name**. +1. Change the default initial branch to a custom name of your choice. +1. 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. + +1. On your local command line, navigate to your `example` repository, and ensure + you're on the default branch: + + ```plaintext + cd example + git checkout master + ``` + +1. Rename the existing default branch to the new name (`main`). The argument `-m` + transfers all commit history to the new branch: + + ```plaintext + git branch -m master main + ``` + +1. Push the newly created `main` branch upstream, and set your local branch to track + the remote branch with the same name: + + ```plaintext + git push -u origin main + ``` + +1. If you plan to remove the old default branch, update `HEAD` to point to your new default branch, `main`: + + ```plaintext + git symbolic-ref refs/remotes/origin/HEAD refs/remotes/origin/main + ``` + +1. Sign in to GitLab as an [administrator](../../../permissions.md) and follow + the instructions to + [change the default branch for this project](#change-the-default-branch-name-for-a-project). + Select `main` as your new default branch. +1. Protect your new `main` branch as described in the [protected branches documentation](../../protected_branches.md). +1. (Optional) If you want to delete the old default branch: + 1. Verify that nothing is pointing to it. + 1. Delete the branch on the remote: + + ```plaintext + 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. + +1. 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. +1. In your repository, update any references to the old branch name in your code. +1. Update references to the old branch name in related code and scripts that reside outside + your repository, such as helper utilities and integrations. + +## Resources + +- [Discussion of default branch renaming](https://lore.kernel.org/git/pull.656.v4.git.1593009996.gitgitgadget@gmail.com/) + on the Git mailing list +- [March 2021 blog post: The new Git default branch name](https://about.gitlab.com/blog/2021/03/10/new-git-default-branch-name/) |