When contributing to open source projects like Mautic, it's standard to have a personal fork of the repo.
Other people do merge in their pull requests (PRs) over time, however, so your fork falls behind the main repository (or "upstream").
This article explains how to:
Whether you are a newcomer to Git or have been working with it for many years, this guide will keep you on the best practices of open-source collaboration.
When you fork Mautic’s repository, you’re essentially making your own copy of it under your GitHub account.
| Term | Meaning |
| Upstream | The original Mautic repository https://github.com/mautic/mautic |
| Origin | Your personal fork of that repo (e.g. https://github.com/YOUR-GITHUB-USERNAME/mautic) |
| Local | The copy on your computer that you work on. |
Keeping your local and origin branches up to date with upstream ensures that your PRs merge smoothly without conflicts
Make sure you have:
Git installed
A cloned fork of Mautic on your local machine
A terminal or Git Bash ready
Verify your remotes:
|
git remote -v |
Expected output (before setting upstream):
|
origin https://github.com/yourusername/mautic.git (fetch) |
To connect your fork to Mautic’s main repo, add an upstream remote:
|
git remote add upstream https://github.com/mautic/mautic.git |
Confirm it’s added correctly:
|
git remote -v |
You should now see:
|
origin https://github.com/yourusername/mautic.git (fetch) |
When the upstream repository changes, you’ll want to update your local default branch and then push it to your fork.
Step 1: Fetch all branches from upstream
|
git fetch upstream |
Step 2: Switch to your local default branch
|
git checkout origin/7.x |
Step 3: Merge upstream changes
|
git merge upstream/x.x |
or (recommended):
|
git rebase upstream/7.x |
Step 4: Push changes to your fork
|
git push origin 7.x |
Now your fork’s 7.x branch is up to date with Mautic’s.
When working on a feature branch, such as feature/improve-login, it’s important to rebase it on top of the latest state of the default branch.
The default branch is the branch in a repository where new changes are merged.
In many open-source projects, it’s called main, but in Mautic it may have a versioned name such as 7.x or 5.2, depending on the development cycle.
Screenshot: The default branch indicator 7.x on Mautic’s GitHub repository.
Now that you know how to identify the default branch, let’s go through the steps to rebase your work properly.
This ensures your feature branch contains the most recent updates from Mautic before you push your changes or open a pull request.
Step 1: Fetch upstream updates
|
git fetch upstream |
Step 2: Switch to your feature branch
|
git checkout feature/improve-login |
Step 3: Rebase onto upstream/main
|
git rebase upstream/7.x |
During rebasing, Git will pause if there are conflicts. Resolve them and continue with:
|
git add . |
If you want to abort the process:
|
git rebase --abort |
Step 4: Push the rebased branch to your fork
Since history changed, use the --force flag carefully:
|
git push origin feature/improve-login --force |
If your local repo gets messy or too far behind, you can completely reset it to match the upstream repository.
Warning: This will overwrite local changes.
|
git fetch upstream |
This command sequence aligns your local and remote main branches exactly with upstream no extra commits, no drift.
Sometimes when rebasing or merging, Git may report a conflict, this means that the same part of a file was changed both in your branch and in the upstream branch. Git can’t automatically decide which version to keep, so it asks you to make that decision manually.
Example output:
|
Auto-merging src/User/Login.php CONFLICT (content): Merge conflict in src/User/Login.php |
Open the conflicting file listed in the message.
Look for conflict markers like these:
|
<<<<<<< HEAD Your version of the code ======= The version from upstream (or the default branch) >>>>>>> upstream/<default-branch> |
iii. Compare both sections carefully.
iv. Decide which version to keep, or combine both if that makes the most sense.
v. Remove the conflict markers (<<<<<<<, =======, >>>>>>>) after editing.
vi. Stage the resolved file and continue the rebase:
|
git add src/User/Login.php git rebase --continue |
Note: When you resolve merge conflicts, it’s a good practice to note what you changed in your pull request description or comments.
This helps reviewers understand what you decided and why.
For example, you might include something like this in your PR comment:
Merge conflict resolution notes:
This level of transparency allows reviewers to check the affected lines more easily and confirm that the resolution aligns with project standards.
|
Problem |
Cause |
Solution |
|
fatal: No upstream configured |
You haven’t added the upstream remote |
Run git remote add upstream https://github.com/mautic/mautic.git |
|
force push rejected |
Branch is protected or you lack permission |
Check PR branch permissions |
|
Conflicts during rebase |
Code differences between upstream and your branch |
Resolve conflicts and continue |
|
Rebase fails completely |
Rebase was aborted |
Try again or reset with git reset --hard upstream/main |
If you get stuck while rebasing or syncing your fork, reach out to the Mautic Product Team on Slack:
Channel: #t-product
You’ll find friendly maintainers who can help guide you through Git issues.
Rebasing and syncing might appear intimidating at first but is in fact one of the most useful Git skills when contributing to open source projects such as Mautic. Having your fork synced to upstream simplifies the lives of maintainers and makes your contributions merge-ready at all times.
Article Number: 238
Author: Nov 22, 2025
Last Updated: Dec 1, 2025
Author: Confidence [[email protected]]
Online URL: https://kb.mautic.org/article/how-to-rebase-and-sync-your-fork-with-upstream-in-git.html