diff options
Diffstat (limited to 'doc/user/project/repository/branches/index.md')
| -rw-r--r-- | doc/user/project/repository/branches/index.md | 300 |
1 files changed, 209 insertions, 91 deletions
diff --git a/doc/user/project/repository/branches/index.md b/doc/user/project/repository/branches/index.md index 60504b94502..7c09ce5c580 100644 --- a/doc/user/project/repository/branches/index.md +++ b/doc/user/project/repository/branches/index.md @@ -6,142 +6,260 @@ info: "To determine the technical writer assigned to the Stage/Group associated # Branches **(FREE)** -A branch is a version of a project's working tree. You create a branch for each -set of related changes you make. This keeps each set of changes separate from -each other, allowing changes to be made in parallel, without affecting each -other. +Branches are versions of a project's working tree. When you create a new +[project](../../index.md), GitLab creates a [default branch](default.md) (which +cannot be deleted) for your repository. Default branch settings can be configured +at the project, subgroup, group, or instance level. -After pushing your changes to a new branch, you can: +As your project grows, your team [creates](../web_editor.md#create-a-branch) more +branches, preferably by following [branch naming patterns](#prefix-branch-names-with-issue-numbers). +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. -- Create a [merge request](../../merge_requests/index.md). You can streamline this process - by following [branch naming patterns](#naming). -- Perform inline code review. -- [Discuss](../../../discussions/index.md) your implementation with your team. -- Preview changes submitted to a new branch with [Review Apps](../../../../ci/review_apps/index.md). +Branches are the foundation of development in a project: -You can also request [approval](../../merge_requests/approvals/index.md) -from your managers. +1. To get started, create a branch and add commits to it. +1. When the work is ready for review, create a [merge request](../../merge_requests/index.md) to propose + merging the changes in your branch. To streamline this process, you should follow + [branch naming patterns](#prefix-branch-names-with-issue-numbers). +1. Preview changes in a branch with a [review app](../../../../ci/review_apps/index.md). +1. After the contents of your branch are merged, [delete the merged branch](#delete-merged-branches). -For more information on managing branches using the GitLab UI, see: +## Create 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-branch) -- [Protected branches](../../protected_branches.md#protected-branches) -- [Delete merged branches](#delete-merged-branches) -- [Branch filter search box](#branch-filter-search-box) +To create a new branch from the GitLab UI: -You can also manage branches using the -[command line](../../../../gitlab-basics/start-using-git.md#create-a-branch). +1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, select **Repository > Branches**. +1. On the top right, select **New branch**. +1. Enter a **Branch name**. +1. In **Create from**, select the base of your branch: an existing branch, an existing + tag, or a commit SHA. +1. Select **Create branch**. -<i class="fa fa-youtube-play youtube" aria-hidden="true"></i>Watch the video [GitLab Flow](https://www.youtube.com/watch?v=InKNIvky2KE). +### In a blank project -See also: +A [blank project](../../index.md#create-a-blank-project) does not contain a branch, but +you can add one. -- [Branches API](../../../../api/branches.md), for information on operating on repository branches using the GitLab API. -- [GitLab Flow](../../../../topics/gitlab_flow.md) documentation. -- [Getting started with Git](../../../../topics/git/index.md) and GitLab. +Prerequisites: -## Naming +- You must have at least the Developer role in the project. +- Unless you have the Maintainer or Owner roles, the + [default branch protection](../../../group/manage.md#change-the-default-branch-protection-of-a-group) + must be set to `Partially protected` or `Not protected` for you to push a commit + to the default branch. -Prefix a branch name with an issue number to streamline merge request creation. -When you create a merge request for a branch with a name beginning with an issue -number, GitLab: +To add a [default branch](default.md) to an empty project: -- Marks the issue as related. If your project is configured with a - [default closing pattern](../../issues/managing_issues.md#default-closing-pattern), - merging this merge request [also closes](../../issues/managing_issues.md#closing-issues-automatically) - the related issue. -- Copies label and milestone metadata from the issue. +1. On the top bar, select **Main menu > Projects** and find your project. +1. Scroll to **The repository for this project is empty** and select the type of + file you want to add. +1. In the Web IDE, make any desired changes to this file, then select **Create commit**. +1. Enter a commit message, and select **Commit**. -## Compare +GitLab creates a default branch and adds your file to it. -To compare branches in a repository: +### From an issue -1. Navigate to your project's repository. -1. Select **Repository > Compare** in the sidebar. -1. Select the target repository to compare with the [repository filter search box](#repository-filter-search-box). -1. Select branches to compare using the [branch filter search box](#branch-filter-search-box). -1. Select **Compare** to view the changes inline: +When viewing an issue, you can create an associated branch directly from that page. -  +Prerequisites: -## Delete merged branches +- You must have at least the Developer role in the project. - +To create a branch from an issue: -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](../../protected_branches.md) are deleted as part of -this operation. +1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, select **Issues** (**{issues}**) and find your issue. +1. Below the issue description, find the **Create merge request** dropdown list, and select + **{chevron-down}** to display the dropdown list. +1. Select **Create branch**. A default **Branch name** is provided, based on the + [default pattern](#configure-default-pattern-for-branch-names-from-issues) for + this project. If desired, enter a different **Branch name**. +1. Select **Create branch** to create the branch based on your project's + [default branch](default.md). -It's particularly useful to clean up old branches that were not deleted -automatically when a merge request was merged. +## 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: -## Repository filter search box +- The [default branch](default.md) in your project receives extra protection. +- Configure [protected branches](../../protected_branches.md#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](../../merge_requests/approvals/rules.md) to set review + requirements, including [security-related approvals](../../merge_requests/approvals/rules.md#security-approvals), before a branch can merge. +- Integrate with third-party [status checks](../../merge_requests/status_checks.md) + to ensure your branch contents meet your standards of quality. -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/52967) in GitLab 13.10. +You can manage your branches: -This feature allows you to search and select a repository quickly when [comparing branches](#compare). +- With the GitLab user interface. +- With the [command line](../../../../gitlab-basics/start-using-git.md#create-a-branch). +- With the [Branches API](../../../../api/branches.md). - +### View all branches -Search results appear in the following order: +To view and manage your branches in the GitLab user interface: -- Repositories with names exactly matching the search terms. -- Other repositories with names that include search terms, sorted alphabetically. +1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, select **Repository > Branches**. -## Branch filter search box +On this page, you can: - +- See all branches, active branches, or stale branches. +- Create new branches. +- [Compare branches](#compare-branches). +- Delete merged branches. -This feature allows you to search and select branches quickly. Search results appear in the following order: +### View branches with configured protections -- Branches with names that matched search terms exactly. -- Other branches with names that include search terms, sorted alphabetically. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/88279) in GitLab 15.1 with a flag named `branch_rules`. Disabled by default. +> - [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/363170) in GitLab 15.10. +> - [Enabled on self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/363170) in GitLab 15.11 -Sometimes when you have hundreds of branches you may want a more flexible matching pattern. In such cases you can use the following operators: +FLAG: +On self-managed GitLab, by default this feature is available. To hide the feature, ask an administrator to [disable the feature flag](../../../feature_flags.md) named `branch_rules`. +On GitLab.com, this feature is available. -- `^` matches beginning of branch name, for example `^feat` would match `feat/user-authentication` -- `$` matches end of branch name, for example `widget$` would match `feat/search-box-widget` -- `*` wildcard matcher, for example `branch*cache*` would match `fix/branch-search-cache-expiration` +Branches in your repository can be [protected](../../protected_branches.md) in multiple ways. You can: -These operators can be mixed, for example `^chore/*migration$` would match `chore/user-data-migration` +- Limit who can push to the branch. +- Limit who can merge the branch. +- Require approval of all changes. +- Require external tests to pass. -## Swap revisions +The **Branch rules overview** page shows all branches with any configured protections, +and their protection methods: -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/60491) in GitLab 13.12. + - +Prerequisites: -The Swap revisions feature allows you to swap the Source and Target revisions. When the Swap revisions button is selected, the selected revisions for Source and Target is swapped. +- You must have at least the Maintainer role in the project. - +To view the **Branch rules overview** list: -## View branches with configured protections **(FREE SELF)** +1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, select **Settings > Repository**. +1. Expand **Branch Rules** to view all branches with protections. + - To add protections to a new branch: + 1. Select **Add branch rule**. + 1. Select **Create protected branch**. + - To view more information about protections on an existing branch: + 1. Identify the branch you want more information about. + 1. Select **Details** to see information about its: + - [Branch protections](../../protected_branches.md). + - [Approval rules](../../merge_requests/approvals/rules.md). + - [Status checks](../../merge_requests/status_checks.md). -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/88279) in GitLab 15.1 with a flag named `branch_rules`. Disabled by default. +## Name your branch -FLAG: -On self-managed GitLab, by default this feature is not available. To make it available, ask an administrator to [enable the feature flag](../../../feature_flags.md) named `branch_rules`. -On GitLab.com, this feature is not available. -This feature is not ready for production use. +Git enforces [branch name rules](https://git-scm.com/docs/git-check-ref-format) +to help ensure branch names remain compatible with other tools. GitLab +adds extra requirements for branch names, and provides benefits for well-structured branch names. -Branches in your repository can be [protected](../../protected_branches.md) by limiting -who can push to a branch, require approval for those pushed changes, or merge those changes. -To help you track the protections for all branches, the **Branch rules overview** -page shows your branches with their configured rules. +GitLab enforces these additional rules on all branches: -To view the **Branch rules overview** list: +- No spaces are allowed in branch names. +- Branch names with 40 hexadecimal characters are prohibited, because they are similar to Git commit hashes. + +Common software packages, like Docker, may enforce +[additional branch naming restrictions](../../../../administration/packages/container_registry.md#docker-connection-error). + +For best compatibility with other software packages, use only numbers, hyphens (`-`), +underscores (`_`), and lower-case letters from the ASCII standard table. You +can use forward slashes (`/`) and emoji in branch names, but compatibility with other +software packages cannot be guaranteed. + +Branch names with specific formatting offer extra benefits: + +- Streamline your merge request workflow by + [prefixing branch names with issue numbers](#prefix-branch-names-with-issue-numbers). +- Automate [branch protections](../../protected_branches.md) based on branch name. +- Test branch names with [push rules](../push_rules.md) before branches are pushed up to GitLab. +- Define which [CI/CD jobs](../../../../ci/jobs/index.md) to run on merge requests. + +### Configure default pattern for branch names from issues + +By default, GitLab uses the pattern `%{id}-%{title}` when creating a branch from +an issue, but you can change this pattern. + +Prerequisites: + +- You must have at least the Maintainer role for the project. + +To change the default pattern for branches created from issues: 1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > Repository**. -1. Expand **Branch Rules** to view all branches with protections. -1. Select **Details** next to your desired branch to show information about its: - - [Branch protections](../../protected_branches.md). - - [Approval rules](../../merge_requests/approvals/rules.md). - - [Status checks](../../merge_requests/status_checks.md). +1. On the left sidebar, select **Settings > Repository** and expand **Branch defaults**. +1. Scroll to **Branch name template** and enter a value. The field supports these variables: + - `%{id}`: The numeric ID of the issue. + - `%{title}`: The title of the issue, modified to use only characters acceptable in Git branch names. +1. Select **Save changes**. + +### 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 to the merge request. The issue and merge request + display links to each other. +- The branch is connected to the issue. +- If your project is configured with a + [default closing pattern](../../issues/managing_issues.md#default-closing-pattern), + merging the merge request [also closes](../../issues/managing_issues.md#closing-issues-automatically) + the related issue. +- Issue milestone and labels are copied to the merge request. + +## Compare branches + +> - Repository filter search box [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/52967) in GitLab 13.10. +> - Revision swapping [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/60491) in GitLab 13.12. + +The default compare mode uses the `git diff from...to` method, instead of the +`git diff from to` method, to compare branches. The `git diff from...to` method +provides a more human-readable diff, because it does not include unrelated changes +made to the target branch after the source branch was created. + +NOTE: +The `git diff from...to` method shows all changes from a cherry-picked commit as +new changes. It uses the merge base, not the actual commit content, to compare branches. + +To compare branches in a repository: + +1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, select **Repository > Compare revisions**. +1. 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`. +1. Select the **Target** repository and branch. Exact matches are shown first. +1. Select **Compare** to show the list of commits, and changed files. To reverse + the **Source** and **Target**, select **Swap revisions**. + +## 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](../../protected_branches.md) 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. + +## Related topics + +- [Protected branches](../../protected_branches.md) +- [Branches API](../../../../api/branches.md) +- [Protected Branches API](../../../../api/protected_branches.md) +- [Getting started with Git](../../../../topics/git/index.md) ## Troubleshooting |