- Change the default branch name for a project
- Change the default branch name for an instance or group
- Protect initial default branches
- Update the default branch name in your repository
- Default branch rename redirect
When you create a new project, WVS creates a default branch in the repository. A default branch has special configuration options not shared by other branches:
- It cannot be deleted.
- It’s initially protected against 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 WVS administrator. WVS checks first for specific customizations, then checks at a broader level, using the WVS 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.
- If no custom default branch name is set at any level, WVS defaults to
In the WVS web app, you can change the defaults at any level. WVS 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 WVS with at least the Maintainer role.
- In the left navigation menu, go to Project Settings > Version Control.
- Expand Default branch, and select a new default branch.
- Optional. Select the Auto-close referenced issues on default branch checkbox 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
WVS administrators can configure a new default branch name at the instance level or group level.
Group-level custom initial branch name
Users with at least the Owner role of groups and subgroups can configure the default branch name for a group:
- Go to the group Settings > Repository.
- Expand Default branch.
- 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.
Protect initial default branches
WVS administrators and group owners can define branch protections to apply to every repository’s default branch at the instance level and group level with one of the following options:
- Not protected - Both developers and maintainers can push new commits and force push.
- Protected against pushes - Developers cannot push new commits, but are allowed to accept merge requests to the branch. Maintainers can push to the branch.
- Partially protected - Both developers and maintainers can push new commits, but cannot force push.
- Fully protected - Developers cannot push new commits, but maintainers can. No one can force push. .
Update the default branch name in your repository
When changing the default branch name for an existing repository, you should preserve
the history of your default branch by renaming it, instead of creating a new branch. This example
renames a Git repository’s (
example) default branch.
On your local command line, navigate to your
examplerepository, 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
-mtransfers all commit history to the new branch:
git branch -m master main
Push the newly created
mainbranch 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
HEADto point to your new default branch,
git symbolic-ref refs/remotes/origin/HEAD refs/remotes/origin/main
- Sign in to WVS with at least the Maintainer
role and follow the instructions to
change the default branch for this project.
mainas your new default branch.
- Protect your new
mainbranch 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
- 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
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, WVS 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.
For Additional Support, Please Reach out to us on our Discord or by Email.