How to Fix "updates were rejected because the tip of your current branch is behind"

You've finished your work, committed your changes, and you try to push them to the remote repository. But instead of a success message, you get this:

$ git push origin main
To https://github.com/user/repo.git
 ! [rejected]        main -> main (fetch first)
error: failed to push some refs to 'https://github.com/user/repo.git'
hint: Updates were rejected because the tip of your current branch is behind
hint: its remote counterpart. Integrate the remote changes (e.g.
hint: 'git pull ...') before pushing again.
hint: See the 'Note about fast-forwards' in 'git push --help' for details.

This is a very common and important error in Git. It's a safety mechanism to prevent you from accidentally overwriting commits made by your teammates.

The Git Cheat Sheet

No need to remember all Git commands and parameters: get our popular "Git Cheat Sheet" - for free!

What Does This Error Mean?

The message "the tip of your current branch is behind its remote counterpart" means that since the last time you synchronized with the remote, other people have pushed new commits to that same branch. The remote branch has moved forward, and your local branch has not yet incorporated those new commits.

Git is refusing to push your changes because it would overwrite the new commits on the remote. It's forcing you to integrate the remote changes before you can share your own.

This is the same underlying issue as the "not possible to fast-forward" and "divergent branches" errors, but it manifests when you try to push instead of pull.

How to Fix It

The solution, as the hint suggests, is to integrate the remote changes first. You need to pull before you can push.

# Pull the latest changes from the remote
$ git pull origin main

When you run this command, one of two things will happen:

If you have no local commits, Git will simply fast-forward your local branch to match the remote, and you can then push your new work.
If you do have local commits, you now have divergent branches. You'll need to decide how to combine your local work with the new remote work. You can do this by either merging or rebasing.

Option 1: Merge (the Default)

Running git pull by itself will fetch the remote commits and then create a new merge commit to combine your work with the remote work. After the pull is complete, your history will show this merge, and you can then successfully push your changes.

# Pull and create a merge commit
$ git pull origin main

# Now, push your changes (including the merge commit)
$ git push origin main

Option 2: Rebase

Many developers prefer to rebase their changes on top of the remote changes to maintain a clean, linear history. You can do this with the --rebase flag.

# Pull and rebase your local commits on top of the remote changes
$ git pull --rebase origin main

# Now, push your rebased changes
$ git push origin main

This makes it look as if you did all your work after the work on the remote was completed, which can make the project history much easier to read.

A Word of Warning: The Dangers of Force Pushing

You may be wondering whether it's appropriate to run git push --force in this situation. Be extremely careful with this command.

git push --force will overwrite the remote branch with your local branch, deleting any commits that were on the remote but not on your local machine. This can cause your teammates to lose their work and is considered destructive. It should only be used in very specific situations and with the full agreement of your team.

The Golden Rule in Git: Always Pull Before You Push

Seeing this error is a normal part of a collaborative workflow. It's Git doing its job to protect your project's history.

The rule is simple: always pull before you push to make sure you are working with the most up-to-date version of the branch.