Commit d209e0ea authored by Amy Qualls's avatar Amy Qualls

Remove 'master' mentions from Source Code pages

These pages all mentioned 'master' and needed to be updated to point
to either the documentation for default branches, or to use 'main'
instead.
parent 78f95195
......@@ -11,7 +11,7 @@ A branch is an independent line of development in a [project](../user/project/in
When you create a new branch (in your [terminal](start-using-git.md#create-a-branch) or with
[the web interface](../user/project/repository/web_editor.md#create-a-new-branch)),
you are creating a snapshot of a certain branch, usually the main `master` branch,
you are creating a snapshot of a certain branch, usually the main branch,
at its current state. From there, you can start to make your own changes without
affecting the main codebase. The history of your changes is tracked in your branch.
......
......@@ -295,8 +295,9 @@ After you've done that, you can [stage your files](#add-and-commit-local-changes
To work on an up-to-date copy of the project (it is important to do this every time
you start working on a project), you `pull` to get all the changes made by users
since the last time you cloned or pulled the project. Use `master` for the
`<name-of-branch>` to get the main branch code, or the branch name of the branch
since the last time you cloned or pulled the project. Replace `<name-of-branch>`
with the name of your [default branch](../user/project/repository/branches/default.md)
to get the main branch code, or replace it with the branch name of the branch
you are currently working in.
```shell
......@@ -305,7 +306,8 @@ git pull <REMOTE> <name-of-branch>
When you clone a repository, `REMOTE` is typically `origin`. This is where the
repository was cloned from, and it indicates the SSH or HTTPS URL of the repository
on the remote server. `<name-of-branch>` is usually `master`, but it may be any
on the remote server. `<name-of-branch>` is usually the name of your
[default branch](../user/project/repository/branches/default.md), but it may be any
existing branch. You can create additional named remotes and branches as necessary.
You can learn more on how Git manages remote repositories in the
......@@ -330,14 +332,14 @@ to work on a different **branch**.
When you create a branch in a Git repository, you make a copy of its files at the time of branching. You're free
to do whatever you want with the code in your branch without impacting the main branch or other branches. And when
you're ready to bring your changes to the main codebase, you can merge your branch into the default branch
used in your project (such as `master`).
used in your project (such as `main`).
A new branch is often called **feature branch** to differentiate from the
**default branch**.
[default branch](../user/project/repository/branches/default.md).
### Create a branch
To create a new feature branch and work from without affecting the `master`
To create a new feature branch and work from without affecting the default
branch:
```shell
......@@ -348,14 +350,15 @@ Note that Git does **not** accept empty spaces and special characters in branch
names, so use only lowercase letters, numbers, hyphens (`-`), and underscores
(`_`). Do not use capital letters, as it may cause duplications.
### Switch to the master branch
### Switch to the default branch
You are always in a branch when working with Git. The main branch is the master
branch, but you can use the same command to switch to a different branch by
changing `master` to the branch name.
You are always in a branch when working with Git. The
[default branch](../user/project/repository/branches/default.md) can vary depending
on your version of GitLab, but you can alter this command to switch to a different branch by
changing `main` to the branch name:
```shell
git checkout master
git checkout main
```
### Work on an existing branch
......@@ -417,10 +420,10 @@ To push all local commits (saved changes) to the remote repository:
git push <remote> <name-of-branch>
```
For example, to push your local commits to the _`master`_ branch of the _`origin`_ remote:
For example, to push your local commits to the _`main`_ branch of the _`origin`_ remote:
```shell
git push origin master
git push origin main
```
On certain occasions, Git disallows pushes to your repository, and then
......@@ -464,14 +467,15 @@ A Git commit should not usually be reversed, particularly if you already pushed
to the remote repository. Although you can undo a commit, the best option is to avoid
the situation altogether by working carefully.
### Merge a branch with master branch
### Merge a branch with default branch
When you are ready to make all the changes in a branch a permanent addition to
the master branch, you `merge` the two together:
the default branch, you `merge` the two together, changing `<feature-branch>` and
`<default-branch>` to your values:
```shell
git checkout <name-of-branch>
git merge master
git checkout <feature-branch>
git merge <default-branch>
```
## Advanced use of Git through the command line
......
......@@ -9,7 +9,7 @@ type: how-tos
GitLab values encourage the use of [Minimal Viable Change (MVC)](https://about.gitlab.com/handbook/values/#minimal-viable-change-mvc).
However, viable changes are not always small. In such cases, it can help to set up a dedicated feature branch.
People can contribute MRs to that feature branch, without affecting the functionality of the default (usually `master`) branch.
People can contribute MRs to that feature branch, without affecting the functionality of the [default branch](../../user/project/repository/branches/default.md).
Once work on the development branch is complete, then the feature branch can be finally merged into the default branch.
......@@ -19,14 +19,14 @@ GitLab frequently implements this process whenever there is an MVC that requires
This section describes the use case with GitLab [release posts](https://about.gitlab.com/handbook/marketing/blog/release-posts/).
Dozens of GitLab team members contribute to each monthly release post.
In such cases, it may be more efficient to submit an MR on the release post feature branch instead of master.
In such cases, it may be more efficient to submit an MR on the release post feature branch instead of the [default branch](../../user/project/repository/branches/default.md).
In this case, the feature branch would be `release-X-Y`. Assuming the `release-X-Y` branch already exists, you can set up an MR against that branch, with the following steps:
1. Navigate to the main (master) branch:
1. Navigate to the [default branch](../../user/project/repository/branches/default.md) (here, `main`):
```shell
git checkout master
git checkout main
```
1. Make sure you have the latest version of your repository:
......@@ -101,8 +101,8 @@ we have selected `test-branch` as the source, and `release-13-0` as the target.
Request to merge test-branch into release-13-0
```
That confirms you've set up the MR to merge into the specified branch, not master.
That confirms you've set up the MR to merge into the specified branch, not the [default branch](../../user/project/repository/branches/default.md).
1. Proceed with the change as you would with any other MR.
1. When your MR is approved, and an appropriate user merges that MR, you can rest assured that your work is incorporated directly into the feature branch.
When the feature branch is ready, it can then be merged into master.
When the feature branch is ready, it can then be merged into the [default branch](../../user/project/repository/branches/default.md).
......@@ -80,12 +80,13 @@ ensure that the changes you're adding to the codebase do not break any
existing changes added to the target branch _after_ you created your feature
branch.
For example, to update your branch `my-feature-branch` with `master`:
For example, to update your branch `my-feature-branch` with your
[default branch](../../user/project/repository/branches/default.md) (here, using `main`):
1. Fetch the latest changes from `master`:
1. Fetch the latest changes from `main`:
```shell
git fetch origin master
git fetch origin main
```
1. Checkout your feature branch:
......@@ -94,24 +95,24 @@ For example, to update your branch `my-feature-branch` with `master`:
git checkout my-feature-branch
```
1. Rebase it against `master`:
1. Rebase it against `main`:
```shell
git rebase origin/master
git rebase origin/main
```
1. [Force-push](#force-push) to your branch.
When you rebase:
1. Git imports all the commits submitted to `master` _after_ the
1. Git imports all the commits submitted to `main` _after_ the
moment you created your feature branch until the present moment.
1. Git puts the commits you have in your feature branch on top of all
the commits imported from `master`:
the commits imported from `main`:
![Git rebase illustration](img/git_rebase_v13_5.png)
You can replace `master` with any other branch you want to rebase against, for
You can replace `main` with any other branch you want to rebase against, for
example, `release-10-3`. You can also replace `origin` with other remote
repositories, for example, `upstream`. To check what remotes you have linked to your local
repository, you can run `git remote -v`.
......
......@@ -354,7 +354,7 @@ GitLab). There is a `git merge --squash` command which does exactly that
at merge).
NOTE:
Never modify the commit history of `master` or shared branch.
Never modify the commit history of your [default branch](../../../user/project/repository/branches/default.md) or shared branch.
### How modifying history is done
......
......@@ -180,12 +180,13 @@ Git includes a complete set of [traces for debugging Git commands](https://git-s
## Rebasing
### Rebase your branch onto master
### Rebase your branch onto the default
The `-i` flag stands for 'interactive':
The `-i` flag stands for 'interactive'. Replace `<default-branch>` with the name
of your [default branch](../../user/project/repository/branches/default.md):
```shell
git rebase -i master
git rebase -i <default-branch>
```
### Continue the rebase if paused
......
......@@ -45,13 +45,13 @@ For a video introduction of how this works in GitLab, see [GitLab Flow](https://
<!-- vale gitlab.Spelling = YES -->
Git flow was one of the first proposals to use Git branches, and it has received a lot of attention.
It suggests a `master` branch and a separate `develop` branch, as well as supporting branches for features, releases, and hotfixes.
The development happens on the `develop` branch, moves to a release branch, and is finally merged into the `master` branch.
It suggests a `main` branch and a separate `develop` branch, as well as supporting branches for features, releases, and hotfixes.
The development happens on the `develop` branch, moves to a release branch, and is finally merged into the `main` branch.
Git flow is a well-defined standard, but its complexity introduces two problems.
The first problem is that developers must use the `develop` branch and not `master`. `master` is reserved for code that is released to production.
It is a convention to call your default branch `master` and to mostly branch from and merge to this.
Because most tools automatically use the `master` branch as the default, it is annoying to have to switch to another branch.
The first problem is that developers must use the `develop` branch and not `main`. `main` is reserved for code that is released to production.
It is a convention to call your default branch `main` and to mostly branch from and merge to this.
Because most tools automatically use the `main` branch as the default, it is annoying to have to switch to another branch.
The second problem of Git flow is the complexity introduced by the hotfix and release branches.
These branches can be a good idea for some organizations but are overkill for the vast majority of them.
......@@ -59,7 +59,7 @@ Nowadays, most organizations practice continuous delivery, which means that your
Continuous delivery removes the need for hotfix and release branches, including all the ceremony they introduce.
An example of this ceremony is the merging back of release branches.
Though specialized tools do exist to solve this, they require documentation and add complexity.
Frequently, developers make mistakes such as merging changes only into `master` and not into the `develop` branch.
Frequently, developers make mistakes such as merging changes only into `main` and not into the `develop` branch.
The reason for these errors is that Git flow is too complicated for most use cases.
For example, many projects do releases but don't need to do hotfixes.
......@@ -68,10 +68,10 @@ For example, many projects do releases but don't need to do hotfixes.
![Branch with feature branches merged in](img/gitlab_flow_github_flow.png)
In reaction to Git flow, GitHub created a simpler alternative.
[GitHub flow](https://guides.github.com/introduction/flow/index.html) has only feature branches and a `master` branch.
[GitHub flow](https://guides.github.com/introduction/flow/index.html) has only feature branches and a `main` branch.
This flow is clean and straightforward, and many organizations have adopted it with great success.
Atlassian recommends [a similar strategy](https://www.atlassian.com/blog/git/simple-git-workflow-is-simple), although they rebase feature branches.
Merging everything into the `master` branch and frequently deploying means you minimize the amount of unreleased code. This approach is in line with lean and continuous delivery best practices.
Merging everything into the `main` branch and frequently deploying means you minimize the amount of unreleased code. This approach is in line with lean and continuous delivery best practices.
However, this flow still leaves a lot of questions unanswered regarding deployments, environments, releases, and integrations with issues.
With GitLab flow, we offer additional guidance for these questions.
......@@ -88,7 +88,7 @@ While this is possible in some cases, such as SaaS applications, there are some
operations team is at full capacity - but you also merge code at other times.
In these cases, you can make a production branch that reflects the deployed code.
You can deploy a new version by merging `master` into the production branch.
You can deploy a new version by merging `main` into the production branch.
If you need to know what code is in production, you can check out the production branch to see.
The approximate time of deployment is visible as the merge commit in the version control system.
This time is pretty accurate if you automatically deploy your production branch.
......@@ -99,16 +99,16 @@ This flow prevents the overhead of releasing, tagging, and merging that happens
![Multiple branches with the code cascading from one to another](img/gitlab_flow_environment_branches.png)
It might be a good idea to have an environment that is automatically updated to the `master` branch.
It might be a good idea to have an environment that is automatically updated to the `main` branch.
Only, in this case, the name of this environment might differ from the branch name.
Suppose you have a staging environment, a pre-production environment, and a production environment.
In this case, deploy the `master` branch to staging.
To deploy to pre-production, create a merge request from the `master` branch to the pre-production branch.
In this case, deploy the `main` branch to staging.
To deploy to pre-production, create a merge request from the `main` branch to the pre-production branch.
Go live by merging the pre-production branch into the production branch.
This workflow, where commits only flow downstream, ensures that everything is tested in all environments.
If you need to cherry-pick a commit with a hotfix, it is common to develop it on a feature branch and merge it into `master` with a merge request.
If you need to cherry-pick a commit with a hotfix, it is common to develop it on a feature branch and merge it into `main` with a merge request.
In this case, do not delete the feature branch yet.
If `master` passes automatic testing, you then merge the feature branch into the other branches.
If `main` passes automatic testing, you then merge the feature branch into the other branches.
If this is not possible because more manual testing is required, you can send merge requests from the feature branch to the downstream branches.
## Release branches with GitLab flow
......@@ -117,15 +117,15 @@ If this is not possible because more manual testing is required, you can send me
You only need to work with release branches if you need to release software to the outside world.
In this case, each branch contains a minor version, such as `2-3-stable` or `2-4-stable`.
Create stable branches using `master` as a starting point, and branch as late as possible.
Create stable branches using `main` as a starting point, and branch as late as possible.
By doing this, you minimize the length of time during which you have to apply bug fixes to multiple branches.
After announcing a release branch, only add serious bug fixes to the branch.
If possible, first merge these bug fixes into `master`, and then cherry-pick them into the release branch.
If you start by merging into the release branch, you might forget to cherry-pick them into `master`, and then you'd encounter the same bug in subsequent releases.
Merging into `master` and then cherry-picking into release is called an "upstream first" policy, which is also practiced by [Google](https://www.chromium.org/chromium-os/chromiumos-design-docs/upstream-first) and [Red Hat](https://www.redhat.com/en/blog/a-community-for-using-openstack-with-red-hat-rdo).
If possible, first merge these bug fixes into `main`, and then cherry-pick them into the release branch.
If you start by merging into the release branch, you might forget to cherry-pick them into `main`, and then you'd encounter the same bug in subsequent releases.
Merging into `main` and then cherry-picking into release is called an "upstream first" policy, which is also practiced by [Google](https://www.chromium.org/chromium-os/chromiumos-design-docs/upstream-first) and [Red Hat](https://www.redhat.com/en/blog/a-community-for-using-openstack-with-red-hat-rdo).
Every time you include a bug fix in a release branch, increase the patch version (to comply with [Semantic Versioning](https://semver.org/)) by setting a new tag.
Some projects also have a stable branch that points to the same commit as the latest released branch.
In this flow, it is not common to have a production branch (or Git flow `master` branch).
In this flow, it is not common to have a production branch (or Git flow `main` branch).
## Merge/pull requests with GitLab flow
......@@ -151,7 +151,7 @@ Also, mention any other people from whom you would like feedback.
After the assigned person feels comfortable with the result, they can merge the branch.
If the assigned person does not feel comfortable, they can request more changes or close the merge request without merging.
In GitLab, it is common to protect the long-lived branches, such as the `master` branch, so [most developers can't modify them](../user/permissions.md).
In GitLab, it is common to protect the long-lived branches, such as the `main` branch, so [most developers can't modify them](../user/permissions.md).
So, if you want to merge into a protected branch, assign your merge request to someone with maintainer permissions.
After you merge a feature branch, you should remove it from the source control software.
......@@ -178,7 +178,7 @@ In many organizations, raising an issue is part of the development process becau
The issue title should describe the desired state of the system.
For example, the issue title "As an administrator, I want to remove users without receiving an error" is better than "Administrators can't remove users."
When you are ready to code, create a branch for the issue from the `master` branch.
When you are ready to code, create a branch for the issue from the `main` branch.
This branch is the place for any work related to this change.
NOTE:
......@@ -188,11 +188,11 @@ When you are done or want to discuss the code, open a merge request.
A merge request is an online place to discuss the change and review the code.
If you open the merge request but do not assign it to anyone, it is a [draft merge request](../user/project/merge_requests/drafts.md).
These are used to discuss the proposed implementation but are not ready for inclusion in the `master` branch yet.
These are used to discuss the proposed implementation but are not ready for inclusion in the `main` branch yet.
Start the title of the merge request with `[Draft]`, `Draft:` or `(Draft)` to prevent it from being merged before it's ready.
When you think the code is ready, assign the merge request to a reviewer.
The reviewer can merge the changes when they think the code is ready for inclusion in the `master` branch.
The reviewer can merge the changes when they think the code is ready for inclusion in the `main` branch.
When they press the merge button, GitLab merges the code and creates a merge commit that makes this event visible later on.
Merge requests always create a merge commit, even when the branch could be merged without one.
This merge strategy is called "no fast-forward" in Git.
......@@ -247,18 +247,18 @@ Git does not allow you to merge the code again otherwise.
Having lots of merge commits can make your repository history messy.
Therefore, you should try to avoid merge commits in feature branches.
Often, people avoid merge commits by just using rebase to reorder their commits after the commits on the `master` branch.
Using rebase prevents a merge commit when merging `master` into your feature branch, and it creates a neat linear history.
Often, people avoid merge commits by just using rebase to reorder their commits after the commits on the `main` branch.
Using rebase prevents a merge commit when merging `main` into your feature branch, and it creates a neat linear history.
However, as discussed in [the section about rebasing](#squashing-commits-with-rebase), you should avoid rebasing commits in a feature branch that you're sharing with others.
Rebasing could create more work, as every time you rebase, you may need to resolve the same conflicts.
Sometimes you can reuse recorded resolutions (`rerere`), but merging is better, because you only have to resolve conflicts once.
Atlassian has a more thorough explanation of the tradeoffs between merging and rebasing [on their blog](https://www.atlassian.com/blog/git/git-team-workflows-merge-or-rebase).
A good way to prevent creating many merge commits is to not frequently merge `master` into the feature branch.
There are three reasons to merge in `master`: utilizing new code, resolving merge conflicts, and updating long-running branches.
A good way to prevent creating many merge commits is to not frequently merge `main` into the feature branch.
There are three reasons to merge in `main`: utilizing new code, resolving merge conflicts, and updating long-running branches.
If you need to use some code that was introduced in `master` after you created the feature branch, you can often solve this by just cherry-picking a commit.
If you need to use some code that was introduced in `main` after you created the feature branch, you can often solve this by just cherry-picking a commit.
If your feature branch has a merge conflict, creating a merge commit is a standard way of solving this.
......@@ -272,9 +272,9 @@ Most feature branches should take less than one day of work.
If your feature branches often take more than a day of work, try to split your features into smaller units of work.
If you need to keep a feature branch open for more than a day, there are a few strategies to keep it up-to-date.
One option is to use continuous integration (CI) to merge in `master` at the start of the day.
One option is to use continuous integration (CI) to merge in `main` at the start of the day.
Another option is to only merge in from well-defined points in time, for example, a tagged release.
You could also use [feature toggles](https://martinfowler.com/bliki/FeatureToggle.html) to hide incomplete features so you can still merge back into `master` every day.
You could also use [feature toggles](https://martinfowler.com/bliki/FeatureToggle.html) to hide incomplete features so you can still merge back into `main` every day.
NOTE:
Don't confuse automatic branch testing with continuous integration.
......@@ -327,26 +327,26 @@ Issue: gitlab.com/gitlab-org/gitlab/-/issues/1
![Merge requests showing the test states: red, yellow, and green](img/gitlab_flow_ci_mr.png)
In old workflows, the continuous integration (CI) server commonly ran tests on the `master` branch only.
Developers had to ensure their code did not break the `master` branch.
When using GitLab flow, developers create their branches from this `master` branch, so it is essential that it never breaks.
In old workflows, the continuous integration (CI) server commonly ran tests on the `main` branch only.
Developers had to ensure their code did not break the `main` branch.
When using GitLab flow, developers create their branches from this `main` branch, so it is essential that it never breaks.
Therefore, each merge request must be tested before it is accepted.
CI software like Travis CI and GitLab CI/CD show the build results right in the merge request itself to simplify the process.
There is one drawback to testing merge requests: the CI server only tests the feature branch itself, not the merged result.
Ideally, the server could also test the `master` branch after each change.
However, retesting on every commit to `master` is computationally expensive and means you are more frequently waiting for test results.
Ideally, the server could also test the `main` branch after each change.
However, retesting on every commit to `main` is computationally expensive and means you are more frequently waiting for test results.
Because feature branches should be short-lived, testing just the branch is an acceptable risk.
If new commits in `master` cause merge conflicts with the feature branch, merge `master` back into the branch to make the CI server re-run the tests.
If new commits in `main` cause merge conflicts with the feature branch, merge `main` back into the branch to make the CI server re-run the tests.
As said before, if you often have feature branches that last for more than a few days, you should make your issues smaller.
## Working with feature branches
![Shell output showing git pull output](img/gitlab_flow_git_pull.png)
When creating a feature branch, always branch from an up-to-date `master`.
When creating a feature branch, always branch from an up-to-date `main`.
If you know before you start that your work depends on another branch, you can also branch from there.
If you need to merge in another branch after starting, explain the reason in the merge commit.
If you have not pushed your commits to a shared location yet, you can also incorporate changes by rebasing on `master` or another feature branch.
If you have not pushed your commits to a shared location yet, you can also incorporate changes by rebasing on `main` or another feature branch.
Do not merge from upstream again if your code can work and merge cleanly without doing so.
Merging only when needed prevents creating merge commits in your feature branch that later end up littering the `master` history.
Merging only when needed prevents creating merge commits in your feature branch that later end up littering the `main` history.
......@@ -17,8 +17,11 @@ To access the visibility and access control options:
## Default branch protection
This global option defines the branch protection that applies to every repository's default branch. [Branch protection](../../project/protected_branches.md) specifies which roles can push to branches and which roles can delete
branches. In this case _Default_ refers to a repository's default branch, which in most cases is `master`.
This global option defines the branch protection that applies to every repository's
[default branch](../../project/repository/branches/default.md).
[Branch protection](../../project/protected_branches.md) specifies which roles can push
to branches and which roles can delete branches. In this case _Default_ refers to a
repository's [default branch](../../project/repository/branches/default.md).
This setting applies only to each repositories' default branch. To protect other branches, you must configure branch protection in repository. For details, see [protected branches](../../project/protected_branches.md).
......
......@@ -201,8 +201,8 @@ This process allows you to lock one file at a time through the GitLab UI and
requires access to [GitLab Premium](https://about.gitlab.com/pricing/)
or higher tiers.
Default branch file and directory locks only apply to the default branch set in
the project's settings (usually `master`).
Default branch file and directory locks only apply to the
[default branch](repository/branches/default.md) set in the project's settings.
Changes to locked files on the default branch are blocked, including merge
requests that modify locked files. Unlock the file to allow changes.
......
......@@ -45,7 +45,7 @@ To disable highlighting entirely, use `gitlab-language=text`. Lots more fun shen
```
Please note that these configurations only take effect when the `.gitattributes`
file is in your default branch (usually `master`).
file is in your [default branch](repository/branches/default.md).
NOTE:
The Web IDE does not support `.gitattribute` files, but it's [planned for a future release](https://gitlab.com/gitlab-org/gitlab/-/issues/22014).
......
......@@ -93,14 +93,14 @@ You can also create and modify project push mirrors through the
By default, if any ref on the remote mirror has diverged from the local
repository, the *entire push* fails, and no updates occur.
For example, if a repository has `master`, `develop`, and `stable` branches that
For example, if a repository has `main`, `develop`, and `stable` branches that
have been mirrored to a remote, and then a new commit is added to `develop` on
the mirror, the next push attempt fails, leaving `master` and `stable`
the mirror, the next push attempt fails, leaving `main` and `stable`
out-of-date despite not having diverged. No change on any branch can be mirrored
until the divergence is resolved.
With the **Keep divergent refs** option enabled, the `develop` branch is
skipped, allowing `master` and `stable` to be updated. The mirror status
skipped, allowing `main` and `stable` to be updated. The mirror status
reflects that `develop` has diverged and was skipped, and be marked as a failed
update.
......
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