Commit 4156f569 authored by Amy Qualls's avatar Amy Qualls

Merge branch 'docs-change-default-branch-name' into 'master'

Add docs for changing default branch name on existing repos

See merge request gitlab-org/gitlab!56258
parents 4a9f16cf c657a7e5
......@@ -769,7 +769,7 @@ Parameters:
### Options for `default_branch_protection`
The `default_branch_protection` attribute determines whether developers and maintainers can push to the applicable master branch, as described in the following table:
The `default_branch_protection` attribute determines whether developers and maintainers can push to the applicable [default branch](../user/project/repository/branches/default.md), as described in the following table:
| Value | Description |
|-------|-------------------------------------------------------------------------------------------------------------|
......
......@@ -1127,7 +1127,7 @@ POST /projects
| `ci_config_path` | string | **{dotted-circle}** No | The path to CI configuration file. |
| `container_expiration_policy_attributes` | hash | **{dotted-circle}** No | Update the image cleanup policy for this project. Accepts: `cadence` (string), `keep_n` (integer), `older_than` (string), `name_regex` (string), `name_regex_delete` (string), `name_regex_keep` (string), `enabled` (boolean). |
| `container_registry_enabled` | boolean | **{dotted-circle}** No | Enable container registry for this project. |
| `default_branch` | string | **{dotted-circle}** No | `master` by default. |
| `default_branch` | string | **{dotted-circle}** No | The [default branch](../user/project/repository/branches/default.md) name. |
| `description` | string | **{dotted-circle}** No | Short project description. |
| `emails_disabled` | boolean | **{dotted-circle}** No | Disable email notifications. |
| `external_authorization_classification_label` **(PREMIUM)** | string | **{dotted-circle}** No | The classification label for the project. |
......@@ -1276,7 +1276,7 @@ PUT /projects/:id
| `ci_forward_deployment_enabled` | boolean | **{dotted-circle}** No | When a new deployment job starts, [skip older deployment jobs](../ci/pipelines/settings.md#skip-outdated-deployment-jobs) that are still pending |
| `container_expiration_policy_attributes` | hash | **{dotted-circle}** No | Update the image cleanup policy for this project. Accepts: `cadence` (string), `keep_n` (integer), `older_than` (string), `name_regex` (string), `name_regex_delete` (string), `name_regex_keep` (string), `enabled` (boolean). |
| `container_registry_enabled` | boolean | **{dotted-circle}** No | Enable container registry for this project. |
| `default_branch` | string | **{dotted-circle}** No | `master` by default. |
| `default_branch` | string | **{dotted-circle}** No | The [default branch](../user/project/repository/branches/default.md) name. |
| `description` | string | **{dotted-circle}** No | Short project description. |
| `emails_disabled` | boolean | **{dotted-circle}** No | Disable email notifications. |
| `external_authorization_classification_label` **(PREMIUM)** | string | **{dotted-circle}** No | The classification label for the project. |
......
......@@ -46,7 +46,7 @@ Access the default page for admin area settings by navigating to **Admin Area >
| Option | Description |
| ------ | ----------- |
| [Repository's custom initial branch name](../../project/repository/branches/index.md#custom-initial-branch-name) | Set a custom branch name rather than master for all the new repositories created within your instance. |
| [Repository's custom initial branch name](../../project/repository/branches/default.md#instance-level-custom-initial-branch-name) | Set a custom branch name for new repositories created in your instance. |
| [Repository mirror](visibility_and_access_controls.md#allow-mirrors-to-be-set-up-for-projects) | Configure repository mirroring. |
| [Repository storage](../../../administration/repository_storage_types.md) | Configure storage path settings. |
| Repository maintenance | ([Repository checks](../../../administration/repository_checks.md) and [Housekeeping](../../../administration/housekeeping.md)). Configure automatic Git checks and housekeeping on repositories. |
......
......@@ -152,7 +152,7 @@ found in those projects' default branches.
## Keeping the dashboards up to date
The Security Dashboard displays information from the results of the most recent
security scan on the [default branch](../../project/repository/branches/index.md#default-branch),
security scan on the [default branch](../../project/repository/branches/default.md),
which means that security scans are performed every time the branch is updated.
If the default branch is updated infrequently, scans are run infrequently and the
......
......@@ -387,16 +387,10 @@ because the project cannot be moved.
> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/43290) in GitLab 13.6.
By default, when you create a new project in GitLab, the initial branch is called `master`.
For groups, a group owner can customize the initial branch name to something
else. This way, every new project created under that group from then on starts from the custom branch name rather than `master`.
To use a custom name for the initial branch:
1. Go to the group's **Settings > Repository** page.
1. Expand the **Default initial branch name** section.
1. Change the default initial branch to a custom name of your choice.
1. Select **Save changes**.
When you create a new project in GitLab, a default branch is created with the
first push. The group owner can
[customize the initial branch](../project/repository/branches/default.md#group-level-custom-initial-branch-name)
for the group's projects to meet your group's needs.
## Remove a group
......@@ -467,7 +461,7 @@ For more information, [see this issue](https://gitlab.com/gitlab-org/gitlab/-/is
To ensure only people from your organization can access particular
resources, you can restrict access to groups by IP address. This setting applies to all subgroups,
projects, issues, and so on.
projects, issues, and so on.
IP access restrictions can be configured at the group level only.
......
......@@ -69,7 +69,7 @@ For each day that a coverage report was generated by a job in a project's pipeli
If the project's code coverage was calculated more than once in a day, we will take the last value from that day.
NOTE:
[In GitLab 13.7 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/270102), group code coverage data is taken from the configured [default branch](../../project/repository/branches/index.md#default-branch). In earlier versions, it is taken from the `master` branch.
[In GitLab 13.7 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/270102), group code coverage data is taken from the configured [default branch](../../project/repository/branches/default.md). In earlier versions, it is taken from the `master` branch.
<!-- ## Troubleshooting
......
......@@ -199,7 +199,7 @@ can be closed automatically when the commit reaches the project's default branch
If a commit message or merge request description contains text matching a [defined pattern](#default-closing-pattern),
all issues referenced in the matched text are closed. This happens when the commit
is pushed to a project's [**default** branch](../repository/branches/index.md#default-branch),
is pushed to a project's [**default** branch](../repository/branches/default.md),
or when a commit or merge request is merged into it.
For example, if `Closes #4, #6, Related to #5` is included in a Merge Request
......
......@@ -26,7 +26,7 @@ By default, a protected branch does these things:
- GitLab administrators are allowed to push to the protected branches.
- Users with [Developer permissions](../permissions.md) are allowed to
create a project in a group, but might not be allowed to initially
push to the [default branch](repository/branches/index.md#default-branch).
push to the [default branch](repository/branches/default.md).
The default branch protection level is set in the [Admin Area](../admin_area/settings/visibility_and_access_controls.md#default-branch-protection).
......
---
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/)
......@@ -24,7 +24,9 @@ With [GitLab Starter](https://about.gitlab.com/pricing/), you can also request
For more information on managing branches using the GitLab UI, see:
- [Default branches](#default-branch)
- [Default branches](default.md): When you create a new [project](../../index.md), GitLab creates a
default branch for the repository. You can change this setting at the project,
subgroup, group, or instance level.
- [Create a branch](../web_editor.md#create-a-new-branch)
- [Protected branches](../../protected_branches.md#protected-branches)
- [Delete merged branches](#delete-merged-branches)
......@@ -41,55 +43,6 @@ See also:
- [GitLab Flow](../../../../university/training/gitlab_flow.md) documentation.
- [Getting started with Git](../../../../topics/git/index.md) and GitLab.
## Default branch
When you create a new [project](../../index.md), GitLab sets `master` as the default
branch of the repository. You can choose another branch to be your project's
default under your project's **Settings > Repository**.
When closing issues directly from merge requests through the [issue closing pattern](../../issues/managing_issues.md#closing-issues-automatically),
the target is the project's **default branch**.
The default branch is also initially [protected](../../protected_branches.md#protected-branches)
against accidental deletion and forced pushes.
### 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's enabled on GitLab.com.
> - 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). **(FREE SELF)**
By default, when you create a new project in GitLab, the initial branch is called `master`.
For self-managed instances, a GitLab administrator can customize the initial branch name to something
else. This way, every new project created from then on starts from the custom branch name rather than `master`. To do so:
1. Go to the **Admin Area > Settings > Repository** and expand **Default initial
branch name**.
1. Change the default initial branch to a custom name of your choice.
1. **Save Changes**.
#### 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)
```
## Compare
To compare branches in a repository:
......
......@@ -21,7 +21,7 @@ functionality of a project.
### General project settings
Adjust your project's name, description, avatar, [default branch](../repository/branches/index.md#default-branch), and topics:
Adjust your project's name, description, avatar, [default branch](../repository/branches/default.md), and topics:
![general project settings](img/general_settings.png)
......
......@@ -9,7 +9,7 @@
%button.btn.gl-button.btn-default.js-settings-toggle{ type: 'button' }
= expanded ? _('Collapse') : _('Expand')
%p
- default_branch_docs = link_to(_("default branch"), help_page_path('user/project/repository/branches/index.md', anchor: 'default-branch'))
- default_branch_docs = link_to(_("default branch"), help_page_path('user/project/repository/branches/default.md'))
= _("Pipeline subscriptions trigger a new pipeline on the default branch of this project when a pipeline successfully completes for a new tag on the %{default_branch_docs} of the subscribed project.").html_safe % { default_branch_docs: default_branch_docs }
%p
= _("A limit of %{ci_project_subscriptions_limit} subscriptions to or from a project applies.").html_safe % { ci_project_subscriptions_limit: @project.actual_limits.ci_project_subscriptions }
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment