Forking and Branching
Before you start working on code and creating PRs, you need to fork and branch. This page will help get you started!
If you need more help with Git commands and concepts, see the Git documentation.
When contributing to the Magento2 repository and special projects, we require that you use a fork for your branches and code. A fork a copy of the current state of a code base into your users repository list, note that forks are not automatically updated but we will cover this in (link for how to keep your fork updated section).
For this example we will use the Magento 2 repository. You can find more repos
- Navigate to the Magento2 repository https://github.com/magento/magento2.
- Select Fork in the top right hand corner.
When completed, you can access your fork through your GitHub account. The link is https://github.com/username/magento2 with your GitHub username for the username.
To start working on your local, you will need to clone your new fork on your development machine using the following command:
git clone git@github.com:username/magento2.git
By default this will clone your fork into a magento2 folder in the current directory. You can also define a folder name as an optional parameter in the clone command, for example:
git clone git@github.com:username/magento2.git new-folder
More information: https://help.github.com/en/articles/fork-a-repo
We recommend that you create a new branch for each bug or feature that you will work. You want to create your branch from a specific repo branch based on the work you are doing:
- For a feature, your branch should be created from the latest version branch. Currently, this branch is 2.4-develop.
- For a bug fix, your branch should be created from the appropriate release line you are fixing. For example, a bug fix for v2.4.x should be 2.4-develop.
-
Checkout the branch you would like to use as the basis for your branch:
$ git checkout 2.4-develop -
Create and switch to a new branch.
$ git checkout -b feature-branch Switched to a new branch "feature-branch"
You are ready to start coding!
As mentioned before, your fork will quickly become outdated as more community and Magento written fixes are merged into the main repository. To keep your fork updated, you will need to add the original repository that you have forked as a second remote.
To see what remotes you currently have run this command:
git remote --v
This should show your newly cloned repository as the origin remote. For example:
origin git@github.com:username/magento2.git (fetch)
origin git@github.com:username/magento2.git (push)
To add the original repository as an upstream remote, run this command:
git remote add upstream git@github.com:magento/magento2.git
Now when your run git remote --v you should see:
origin git@github.com:username/magento2.git (fetch)
origin git@github.com:username/magento2.git (push)
upstream git@github.com:magento/magento2.git (fetch)
upstream git@github.com:magento/magento2.git (push)
To keep the main branch (currently 2.4-develop) updated, you have two options.
- Fetch and merge the main branch.
- Create your local main branch to track the upstream version and then fetch and pull.
You can also watch this video for additional information.
To fetch the upstream you can run:
git fetch upstream
Then checkout your main branch, currently 2.4-develop.
git checkout 2.4-develop
Now you can merge to upstream version of this branch into your branch:
git merge upstream/2.4-develop
To create a local branch to track the upstream, you can define the tracking branch as an extra parameter when creating the branch on the command-line:
git checkout -b 2.4-develop upstream/2.4-develop
Now once you have fetched the latest changes to upstream, check if your local branch is behind the upstream version. Run this command:
git branch -v
More information: https://help.github.com/en/articles/syncing-a-fork