Fix Git push error: tip of your current branch is behind

What this error means

Git rejects your push when the remote branch has new commits you don’t have locally. The push would not be a fast-forward, so Git stops you to protect others’ work. The error typically reads:

• Updates were rejected because the tip of your current branch is behind

To fix it, bring your local branch up to date with the remote, integrate the remote changes (rebase or merge), resolve conflicts if any, then push.

Quickstart (safe default)

1. Save or stash local changes if uncommitted.

2. Fetch and rebase your local branch on top of the remote branch:

# On your feature branch or main
git fetch origin
git pull --rebase --autostash origin $(git branch --show-current)

1. Resolve conflicts if prompted, then continue:

git status
# edit files to resolve conflicts
git add <file(s)>
git rebase --continue

1. Push the updated branch:

git push

If your branch is protected (e.g., main), push to a feature branch and open a pull request instead.

Minimal working example (reproduce and fix)

# Create a bare "remote" repository
rm -rf /tmp/origin.git /tmp/A /tmp/B
git -c init.defaultBranch=main init --bare /tmp/origin.git

# Clone it twice to simulate two developers
git clone /tmp/origin.git /tmp/A
cd /tmp/A

echo "v1" > file.txt
git add file.txt
git commit -m "init"
# establish main on remote
git branch -M main
git push -u origin main

# Second clone
cd /tmp
git clone /tmp/origin.git /tmp/B

# Dev A makes a change and pushes
cd /tmp/A
echo "from A" >> file.txt
git commit -am "A change"
git push

# Dev B makes a different change and tries to push (will be rejected)
cd /tmp/B
echo "from B" >> file.txt
git commit -am "B change"

git push
# => Updates were rejected because the tip of your current branch is behind

# Fix from B by rebasing onto origin/main, then push
git pull --rebase origin main
# (resolve conflicts if any, then:)
# git add <resolved files>
# git rebase --continue

git push

Step-by-step fixes

1. Confirm your branch and tracking

• Check current branch and upstream:

git status -sb
# or
git rev-parse --abbrev-ref --symbolic-full-name @{u}

• If no upstream is set:

git branch --set-upstream-to=origin/main main

1. Fetch latest remote state

git fetch origin

1. Integrate remote changes (choose one)

• Rebase (keeps linear history)

git pull --rebase origin <branch>

• Merge (creates a merge commit)

git pull --no-rebase origin <branch>

1. Resolve conflicts if any, then continue

git status
# edit files to fix conflicts
git add <files>
# for rebase:
git rebase --continue
# for merge:
git commit

1. Push

git push

When you might need force-with-lease

Only use this when you intend to overwrite remote history (e.g., you rebased a branch you alone own, or you need to back out a bad push you made). It is safer than --force because it refuses to overwrite if the remote moved unexpectedly.

git push --force-with-lease

Never use this on shared branches like main unless your team agrees and branch protection allows it.

Choosing rebase vs merge

• Rebase

  • Pros: linear history, easier to bisect and read.
  • Cons: rewrites commit hashes; don’t rebase public/shared history.

• Merge

  • Pros: preserves original commits; safe for shared branches.
  • Cons: can produce frequent merge commits.

A common DevOps policy: feature branches rebase; main integrates via merge or squash through pull requests.

Handling protected branches

If main is protected from direct pushes:

• Push your local branch to origin with a new name and open a PR:

git push -u origin <feature-name>

• Rebase your feature branch onto origin/main to keep it current before merging via PR:

git fetch origin
git rebase origin/main

Diagnose ahead/behind and divergence

• Show ahead/behind counts:

git status -sb

• See diverged commits relative to origin/main:

git log --oneline --left-right --cherry-pick --graph origin/main...HEAD

• If the remote was force-pushed and you need to match it exactly:

git fetch origin
# WARNING: this discards local commits not on origin/main
git reset --hard origin/main

Common pitfalls

• Using git pull without understanding rebase vs merge, cluttering history.
• Force-pushing to shared branches and deleting teammates’ commits.
• Rebasing a branch that others already based work on.
• Forgetting to stash uncommitted changes before rebase; use --autostash.
• Conflicts from line-ending conversions; align .gitattributes settings (e.g., text=auto) across the team.
• Submodules and Git LFS need their own updates (git submodule update --init --recursive; git lfs pull).

Performance notes for large repos

• Shallow fetch when you only need latest history:

git fetch --depth=1 origin <branch>

• Partial clone to avoid fetching large blobs:

git clone --filter=blob:none <url> <dir>

• Rebase performance: rebase rewrites commits; for long-lived branches with many commits, consider merging instead to avoid replaying a large stack.

• Use sparse-checkout to limit working tree size:

git sparse-checkout init --cone
git sparse-checkout set <dir>

Small checklist

• Do I have uncommitted changes? Stash or commit first.
• Did I fetch the latest remote state? git fetch origin
• Will I rebase (linear) or merge (preserve history)?
• Are there conflicts to resolve? Resolve, then continue.
• Is the branch protected? Use a feature branch and PR.

FAQ

Q: Why did git push fail even though I just pulled? A: Someone pushed after your pull. Fetch and rebase/merge again, then push.

Q: Is git pull --rebase always safe? A: It’s safe for local changes. Avoid rebasing commits that are already shared on a public branch unless the team agrees.

Q: When should I use --force-with-lease? A: Only to update a remote branch after rewriting your local history (e.g., interactive rebase) and only if you’re sure it won’t delete others’ work.

Q: How do I avoid this error in CI/CD? A: Make the CI job fetch and rebase/merge before push. For version bumps, use a dedicated bot branch or a protected workflow with merge queues.

Q: How do I see what I’m about to push? A: Use git log origin/BRANCH..HEAD to list commits that will be pushed.