How to fix This branch is out-of-date with the base branch in Git

GitBEGINNERLOWUpdated Dec 6, 2025· 369 views

This warning appears on GitHub pull requests when your feature branch is behind the base branch (usually main or master). You need to update your branch with the latest changes from the base branch before merging, either by merging or rebasing.

Quick fix

Fixes This branch is out-of-date with the base branch

Two options appear:
- "Update with merge commit" - Creates a merge commit (default)
- "Update with rebase" - Rebases your commits (if enabled by repo settings)
  1. Update branch using GitHub's UI (easiest method)
  2. Update by merging base branch locally
  3. Update by rebasing onto base branch
  4. Handle merge conflicts
git — error
Two options appear:
- "Update with merge commit" - Creates a merge commit (default)
- "Update with rebase" - Rebases your commits (if enabled by repo settings)
This branch is out-of-date with the base branch

What this error means

The message "This branch is out-of-date with the base branch" appears in GitHub's pull request interface when your feature branch doesn't include all the commits that have been added to the base branch since you created or last updated your branch. This happens because Git repositories evolve continuously. While you were working on your feature branch, other developers merged their changes into the base branch (typically `main` or `master`). Your branch has now "diverged" from the base branch—it's missing commits that exist there. GitHub displays this warning because: 1. **Merge conflicts might exist**: The new commits in the base branch might conflict with your changes 2. **Tests might fail**: Your code might work alone but break when combined with new changes 3. **Branch protection rules**: Many repositories require branches to be up-to-date before merging 4. **Code review accuracy**: Reviewers should see how your changes interact with the current codebase

Typical symptoms

  • GitHub PR shows 'This branch is out-of-date with the base branch' message
  • Yellow warning banner appears at the bottom of the PR page
  • 'Update branch' button is displayed on the PR
  • Merge button is disabled with message about branch being out of date
  • CI/CD checks are blocked due to branch protection rules
  • PR shows 'X commits behind main' or similar message
  • GitHub Actions workflows won't run due to outdated branch
  • Merge queue rejects the PR for being out of date

Common causes

  1. Other pull requests were merged into the base branch after you created your branch
  2. Direct commits were pushed to the base branch since your branch was created
  3. Your branch was created a long time ago and significant changes have occurred
  4. Branch protection rules require branches to be up-to-date before merging
  5. A merge queue is configured that requires fresh branches
  6. Someone force-pushed to the base branch, rewriting history
  7. Your branch was based on an older commit rather than the branch tip

How to fix "This branch is out-of-date with the base branch"

1Update branch using GitHub's UI (easiest method)

The simplest way to update your branch is directly through GitHub's web interface:

1. Navigate to your pull request on GitHub
2. Look for the yellow warning banner that says "This branch is out-of-date with the base branch"
3. Click the "Update branch" button

bash
Two options appear:
- "Update with merge commit" - Creates a merge commit (default)
- "Update with rebase" - Rebases your commits (if enabled by repo settings)

Note: The "Update with rebase" option must be enabled in repository settings under Settings > General > Pull Requests > "Allow rebase merging".

This method automatically fetches the latest changes and updates your branch without needing to use the command line.

2Update by merging base branch locally

If you prefer working locally or need more control, merge the base branch into your feature branch:

bash
# Ensure you're on your feature branch
git checkout your-feature-branch

# Fetch the latest changes from remote
git fetch origin

# Merge the base branch into your branch
git merge origin/main

# If there are conflicts, resolve them, then:
git add .
git commit -m "Merge main into feature branch"

# Push the updated branch
git push origin your-feature-branch

This creates a merge commit that brings your branch up to date. Your branch history will show the point where you merged in the base branch changes.

3Update by rebasing onto base branch

Rebasing creates a cleaner history by replaying your commits on top of the base branch:

bash
# Ensure you're on your feature branch
git checkout your-feature-branch

# Fetch the latest changes
git fetch origin

# Rebase your branch onto the base branch
git rebase origin/main

# If conflicts occur, resolve them for each commit:
# 1. Edit conflicting files
# 2. git add <resolved-files>
# 3. git rebase --continue

# Force push since history was rewritten
git push --force-with-lease origin your-feature-branch

Important: Rebasing rewrites commit history. Use --force-with-lease instead of --force to prevent accidentally overwriting others' work if they've pushed to your branch.

Warning: Don't rebase branches that others are working on or that have been reviewed, as it changes commit hashes.

4Handle merge conflicts

If updating causes conflicts, you'll need to resolve them:

bash
# After git merge or during git rebase, if conflicts occur:

# See which files have conflicts
git status

# Open conflicting files - look for conflict markers:
<<<<<<< HEAD
Your changes
=======
Changes from base branch
>>>>>>> origin/main

# Edit the files to resolve conflicts (remove markers, keep correct code)

# After resolving all conflicts:
git add <resolved-files>

# For merge:
git commit -m "Resolve merge conflicts with main"

# For rebase:
git rebase --continue

# Push your changes
git push origin your-feature-branch
# (use --force-with-lease if rebasing)

Tip: Use a merge tool for complex conflicts:

bash
git mergetool
5Configure automatic branch updates (repository setting)

Repository administrators can enable automatic branch updates:

1. Go to repository Settings
2. Navigate to General > Pull Requests
3. Enable "Always suggest updating pull request branches"
4. Optionally enable "Automatically update head branches" for merge queue

For merge queues (GitHub Enterprise or public repos):

yaml
# In branch protection rules, you can require:
- "Require branches to be up to date before merging"
- Configure merge queue settings

This ensures PRs are automatically kept in sync or clearly marked when they need updates.

6Use GitHub CLI to update branch

The GitHub CLI provides a convenient way to sync your branch:

bash
# Install GitHub CLI if needed (https://cli.github.com/)

# Sync your branch with the base branch
gh pr checkout <pr-number>
gh repo sync

# Or use standard git commands through gh:
gh pr checkout <pr-number>
git fetch origin
git merge origin/main
git push

# You can also update via the API:
gh api \
  --method PUT \
  /repos/{owner}/{repo}/pulls/{pull_number}/update-branch \
  -f update_method='merge'

The CLI makes it easy to switch between PRs and keep them updated.

Advanced notes

### Merge vs Rebase: Choosing the Right Strategy

Use Merge when:
- Working in a shared branch with multiple contributors
- You want to preserve the exact history of when changes were integrated
- Your team's workflow prefers merge commits
- The PR has already been reviewed (rebase changes commit hashes)

Use Rebase when:
- You want a linear, clean commit history
- You're the only one working on the branch
- The branch hasn't been reviewed yet
- Your team prefers squash-and-merge or rebase workflows

### Branch Protection Rules

Many organizations configure branch protection rules that require branches to be up-to-date:

yaml
# Common protection settings:
- Require status checks to pass before merging
- Require branches to be up to date before merging
- Require linear history (forces rebase or squash)
- Require merge queue

When "Require branches to be up to date" is enabled:
1. The merge button is disabled if your branch is behind
2. You must update before CI checks will run
3. This prevents "semantic conflicts" where tests pass individually but fail together

### Handling Large Divergence

If your branch is significantly behind (many commits), consider:

bash
# Check how far behind you are
git fetch origin
git rev-list --count HEAD..origin/main
# Shows number of commits you're behind

# If it's substantial, consider:
# 1. Creating a new branch from main
# 2. Cherry-picking your commits
git checkout -b new-feature-branch origin/main
git cherry-pick <commit1> <commit2> ...

# Or use interactive rebase to clean up first
git rebase -i origin/main

### Merge Queue Behavior

GitHub's merge queue works by:
1. Taking PRs that are ready to merge
2. Creating a temporary branch with all queued PRs merged together
3. Running CI on this combined state
4. Merging successful builds, rejecting failures

If your PR is out of date when entering the queue:
- It will be automatically rebased/merged with the current base
- If conflicts occur, your PR is removed from the queue
- You'll need to manually update and re-enter the queue

### Git Configuration for Easier Updates

bash
# Set up convenient aliases
git config --global alias.update '!git fetch origin && git merge origin/main'
git config --global alias.sync '!git fetch origin && git rebase origin/main'

# Configure default behavior for pull
git config --global pull.rebase true  # Prefer rebase on pull
# Or
git config --global pull.rebase false # Prefer merge on pull

# Set up autostash for rebasing
git config --global rebase.autoStash true

### Preventing Out-of-Date Branches

Best practices to minimize this issue:
1. Keep PRs small: Smaller PRs merge faster, less chance of falling behind
2. Merge frequently: Don't let PRs sit for weeks
3. Rebase regularly: If working on a long-running branch, rebase daily
4. Use draft PRs: Create drafts early to catch conflicts sooner
5. Enable branch update notifications: GitHub can notify when your PR needs updating

### CI/CD Considerations

When your branch is out of date:
- Some CI systems won't run until you update
- Tests might pass on your branch but fail when merged
- Consider running tests against a merge of your branch + main:

yaml
# GitHub Actions example
on:
  pull_request:
    types: [opened, synchronize]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          # Checkout the merge commit for accurate testing
          ref: refs/pull/${{ github.event.pull_request.number }}/merge

Frequently asked questions

What does "This branch is out-of-date with the base branch" mean?
The message "This branch is out-of-date with the base branch" appears in GitHub's pull request interface when your feature branch doesn't include all the commits that have been added to the base branch since you created or last updated your branch. This happens because Git repositories evolve continuously. While you were working on your feature branch, other developers merged their changes into the base branch (typically main or master).
How do I fix "This branch is out-of-date with the base branch"?
This warning appears on GitHub pull requests when your feature branch is behind the base branch (usually main or master). You need to update your branch with the latest changes from the base branch before merging, either by merging or rebasing.
What causes "This branch is out-of-date with the base branch"?
Other pull requests were merged into the base branch after you created your branch Direct commits were pushed to the base branch since your branch was created Your branch was created a long time ago and significant changes have occurred
Is the "This branch is out-of-date with the base branch" error serious?
It is a low-severity error — more of a blocker than a risk. The steps above resolve it.

Official resources & further reading