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

### 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:

# 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:

# 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

# 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:

# 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