Updates were rejected because the tip of your current branch is behind its remote counterpart

# Updates were rejected because the tip of your current branch is behind its remote counterpart

The Git error "Updates were rejected because the tip of your current branch is behind its remote counterpart" occurs when you try to push changes to a remote branch that is ahead of your local branch.

Here is the complete stack trace:

Copied!
To github.com:bobbyhadz/bobbyhadz-git.git
 ! [rejected]        master -> master (non-fast-forward)
error: failed to push some refs to 'github.com:bobbyhadz/bobbyhadz-git.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.

When working with Git, you use local and remote branches.

• Local branches are local to your computer and are seen only by you.

You can use the git branch command to view your local branches.

Copied!
git branch

• Remote branches are stored on a remote repository, e.g. GitHub Gitlab or Bitbucket and are seen by all collaborators.

You can use the git branch -r command to view your remote branches.

Copied!
git branch -r

Notice that the name of the remote branch is prefixed with origin/. An easy way to think about it is that origin is equivalent to remote in this case.

If your local branch falls behind its remote counterpart, then the error is raised.

Your local branch might fall behind the remote branch for multiple reasons:

1. Someone else has pushed changes to the remote branch and you haven't yet integrated the changes locally.
2. Someone else has modified the history of the remote with the git rebase command.
3. You have edited a file directly in your browser (e.g. using the GitHub UI) and have committed the changes.

# Integrate the remote changes before pushing

Note: you should only use this approach if your colleagues haven't modified the history of the remote branch with git rebase.

The git rebase command is used to move or combine a sequence of commits to a new base commit.

The command changes the commit history, so you shouldn't use git pull in case git rebase is used.

This can cause duplicate or unordered commits and a merge commit.

If your colleagues haven't used the git rebase command, integrate the remote changes before pushing.

Run the following commands from your terminal.

Copied!
git config pull.rebase false

git pull origin <your_remote_branch>

git status

# Resolve Merge Conflicts (if any)

git add .

git commit -m 'YOUR MESSAGE'

git push origin <your_remote_branch>

Make sure to replace the placeholder with the name of your remote branch.

The git config pull.rebase command is used to set the default Git strategy when pulling from the remote.

The git pull command fetches and downloads the content of the remote branch and updates the local repository automatically.

If you get merge conflicts when issuing the git pull command, you have to follow the instructions to pick which changes you want to keep.

# Overwriting the remote branch with the contents of the local branch

An alternative approach to solving the error is to use the --force option.

By default, the git push command refuses to update a remote that is behind the local branch.

The --force (or -f) flag disables these checks and can cause the repository to lose commits.

The git push -f command basically overwrites the remote branch with the contents of your local branch.

If you simply want to override the remote with your local changes, use the git push command with the -f flag.

Copied!
git push -f origin master

Make sure to replace master with the name of your remote branch.

For example, git push -f origin main if your remote branch is called main.

# Overwriting the local branch with the changes from the remote branch

Conversely, if you need to overwrite all changes in your local branch with the changes from the remote branch, use the git reset --hard command.

Note that this would wipe all your local changes.

Copied!
git reset --hard origin/master

Make sure to replace master with the name of your remote branch.

The git reset --hard command resets the index and the working tree.

Changes to the tracked files are discarded and untracked files or directories are deleted.

# Stash your local changes, reset and then commit your stashed changes

An alternative approach to solve the error is to:

1. Use a soft reset to undo your local commits and leave the changes in the index and the working tree.

Note that a soft reset doesn't delete your files. It simply undoes the specified commits.

2. Stash (shelve) your changes.

3. Do a git reset --hard to overwrite the local branch with the changes from the remote.

4. Use the git stash pop command to un-stash your changes and commit them.

Let's start with the git reset --soft command.

Use the command to undo the last N commits so we can stash the changes.

You can use the git log command if you need to see your git history.

Copied!
git log

Check how many times you've committed locally and use the git reset --soft HEAD~N command.

1. For example, assuming I want to undo the last 2 commits, I would issue the following command.

Copied!
git reset --soft HEAD~2

If you run the git status command, you will see the files that you modified in the specified number of commits in the staging area.

Copied!
git status

2. Run the git stash command to temporarily shelve the changes you've made in the last N commits.

Copied!
git stash

If you run the git status command after running git stash your working tree will be clean.

3. Overwrite your local branch with the changes from the remote branch.

Copied!
git reset --hard origin/master

Make sure to replace master with the name of your remote branch, e.g. main.

At this point, your local repository is up to date with the remote (other than the saved stash).

4. Un-stash your changes with the git stash pop command.

Copied!
git stash pop

The git stash pop command re-applies the most recently created stash.

5. Add your changes and commit your changes from the stash.

Copied!
git add .

git commit -m 'your message'

git push origin <your_remote_branch>

If you need to add your changes in interactive mode, use the git add --patch command.

Copied!
git add --patch

The interactive session will prompt you if you want to stage each change.

# Pushing your changes to a different remote branch

An alternative approach is to push your changes to a different remote branch.

1. Use the git checkout -b command to create a new local branch.

Copied!
git checkout -b your-new-branch

2. Push to a remote branch with the same name.

Copied!
git push origin your-new-branch

Now you can either merge the changes or create a pull request.

# Conclusion

There are multiple ways to solve the error "Updates were rejected because the tip of your current branch is behind its remote counterpart":

1. Pulling the changes from the remote branch and incorporating them into the local branch.
2. Overwriting the remote changes with the local changes.
3. Overwriting the local changes with the remote changes.
4. Using a git stash to stash your local changes and re-apply them after doing a hard reset.
5. Pushing your changes to a different remote branch and opening a pull request.