When you work on a feature branch for more than a day or two, the main branch keeps moving forward. Other developers merge their changes, and your branch falls behind. If you push or open a merge request without updating first, you risk merge conflicts, broken builds, or overwriting someone else’s work.
This guide shows you how to update your feature branch with the latest main branch before pushing, using either merge or rebase.
Prerequisites
- Git installed on your machine (version 2.28 or later recommended) — if you need to upgrade, see How to Upgrade Git to Version 2.41.0 or Later on Ubuntu
- A local Git repository with a remote (
origin) - A feature branch checked out from
main
When Should You Update Your Feature Branch?
You should pull in the latest main before pushing your feature branch in these situations:
- Before opening a merge request or pull request — so reviewers see a clean diff without unrelated conflicts
- After a teammate merges a large change — especially if it touches files you are also editing
- Before running CI/CD pipelines — to make sure your code works with the latest codebase
- When your branch has been open for several days — the longer it lives, the more it drifts from
main
Option 1: Update Feature Branch Using Merge
This is the simplest and safest approach. It creates a merge commit that combines the latest main into your feature branch. Your commit history stays intact.
Step 1: Switch to the Main Branch
git checkout mainThis switches your working directory to the main branch.
Step 2: Pull the Latest Changes
git pull origin mainThis fetches and merges the latest commits from the remote main branch into your local main.
Step 3: Switch Back to Your Feature Branch
git checkout your-feature-branchReplace your-feature-branch with your actual branch name.
Step 4: Merge Main into Your Feature Branch
git merge mainThis brings all the new commits from main into your feature branch. Git creates a merge commit to tie the histories together.
If there are no conflicts, Git completes the merge automatically. If there are conflicts, Git tells you which files need manual resolution. After fixing them:
git add .
git commitFor a deeper look at handling merge conflicts manually, check out How to Merge Branches in Git Without Auto-Resolving Conflicts.
Step 5: Push Your Updated Feature Branch
git push origin your-feature-branchYour feature branch is now up to date with main and pushed to the remote.
Option 2: Update Feature Branch Using Rebase
Rebase replays your feature branch commits on top of the latest main. This produces a linear commit history without merge commits, which some teams prefer for cleaner logs.
Step 1: Fetch the Latest Changes
git fetch origingit fetchdownloads new commits from the remote without merging anything into your local branches
Step 2: Make Sure You Are on Your Feature Branch
git checkout your-feature-branchStep 3: Rebase onto Main
git rebase origin/mainThis takes your feature branch commits and replays them one by one on top of the latest origin/main. If a commit conflicts with something in main, Git pauses and asks you to resolve it.
To resolve conflicts during a rebase:
# Fix the conflicting files, then:
git add .
git rebase --continueIf you want to abort the rebase and go back to how things were:
git rebase --abortStep 4: Push Your Rebased Feature Branch
After a rebase, your local commit history has changed. If you already pushed this branch before, you need a force push:
git push origin your-feature-branch --force-with-lease--force-with-leaseis safer than--forcebecause it checks that no one else has pushed to the branch since your last fetch. If someone did, the push is rejected so you don’t accidentally overwrite their work.
Merge vs. Rebase: Which Should You Use?
| Merge | Rebase | |
|---|---|---|
| Commit history | Keeps all commits plus a merge commit | Linear history, no merge commits |
| Safety | Non-destructive, original commits untouched | Rewrites commit hashes |
| Conflicts | Resolve once during the merge | May need to resolve per commit |
| Force push needed | No | Yes, if branch was already pushed |
| Best for | Shared branches, less experienced teams | Solo branches, clean history preference |
General rule: If you are the only one working on the feature branch, rebase is fine. If others are also committing to the same branch, use merge to avoid rewriting shared history.
Quick Reference: The Full Workflow
Here is the merge approach in a compact form you can copy and run:
git checkout main
git pull origin main
git checkout your-feature-branch
git merge main
git push origin your-feature-branchAnd the rebase approach:
git fetch origin
git checkout your-feature-branch
git rebase origin/main
git push origin your-feature-branch --force-with-leaseTips for Keeping Feature Branches Clean
- Update frequently. The longer you wait, the more conflicts you accumulate. Pull in
mainat least once a day on active projects. - Keep branches short-lived. Small, focused branches that get merged quickly are easier to manage than long-running ones.
- Squash before merging. If your branch has a lot of messy “WIP” commits, consider squashing them into one clean commit before merging into
main. - Stash uncommitted work first. If you have uncommitted changes when switching branches, stash them or move them to a new branch first.
Conclusion
Keeping your feature branch in sync with main before pushing prevents merge conflicts and keeps your team’s workflow smooth. Use git merge main for a safe, straightforward update, or git rebase origin/main for a cleaner commit history.
If you are setting up Git authentication so you can push without password prompts, check out How to Configure Git Pushes Without Authentication Prompts.
