We have all been there — you’re ready to transfer your work from your local repository to a remote repo, only to realize that the trusted git push command is not doing the job.
You may have heard about the --force flag command before, and maybe that has even saved your day in the past. But do you understand how “Force Push” works in the background? Do you know when to avoid it?
If not, don’t worry — after reading this article, you will.
We will break it down into 4 parts:
- Why is "git push" not working?
- What happens when you Force Push
- Is Force Push bad practice? What can I do instead?
- When should I use Force Push?
Let’s dive in!
1. Why Is "git push" Not Working?
Here’s a simple scenario: you are working on the same branch as Joe. You both pulled the latest version from the remote repository in the morning and started working. So far, so good.
Joe has finished his task and pushed his work to the remote repo. Joe is on his way to the gym and you carry on with your assignment. You conclude your work, and now just need to run git push to end your day.
Sadly, an error message is displayed in your terminal window, similar to this:
! [rejected] main -> main (fetch first)
error: failed to push some refs to ...
hint: Updates were rejected because the remote contains work that you do
hint: not have locally. This is usually caused by another repository pushing
hint: to the same ref. You may want to first integrate the remote changes
hint: (e.g., 'git pull ...') before pushing again.
hint: See the 'Note about fast-forwards' in 'git push --help' for details.
Well, why is it not working?
Unlike other version control systems, Git does not allow any conflicts on the remote repository. This is a good thing because it reassures you that the repo is in a healthy state at all times.
You won’t be overwriting commits from the team by accident but, at the same time, this means you will always need to pull any outstanding changes before pushing your work. And since Joe committed his work in the meantime, the repo’s history changed and you aren’t up to date anymore.
If you have a look at Git’s official documentation, you will quickly notice that you can force this command. You can use the --force flag (or -f for short).
This can look like an easy workaround when the git push command does not work, but it is rarely recommended — it’s not the default behavior for a reason.
In the scenario above, if you force push your work, you will erase Joe’s commit from the remote repo. Joe won’t be happy when he’s back from the gym!
Does this mean that we should avoid Force Pushing at all costs? Not necessarily. Let’s start by understanding what’s happening in the background…
2. What Happens When You Force Push
Every time you Force Push, you’re basically rewriting history. Ever seen a movie where the character goes back in time, changes history, and everything goes well? Me neither.
Whenever you run the git push command, Git has a look at your local repository and copies to the remote side whatever is missing. This includes commits, trees, blobs, and tags (the last of which are not pushed by default).
After copying the missing content, Git attempts to overwrite the current master with the latest commit. This overwrite is allowed if the change is a “fast forward”, that is, if the old master commit is an ancestor of the new master commit.
If there is a linear path, the command succeeds. When it’s not allowed (most likely because the remote repo looked different from yours, apart from your new commits), the command fails.
The command will always succeed, however, if you resort to the --force flag. You will overwrite the remote’s commit history with your local one, regardless of how different it looks.
As you can see, this is a powerful command — but, as a famous web-slinger once taught us, "with great power comes great responsibility".
So should you use it?
3. Is Force Push Bad Practice? What Can I Do Instead?
There are some situations where running git push --force actually makes sense, but on most occasions, you should stay away from typing it. It’s rarely the best approach to the problem.
There are 2 big reasons for this:
- There’s a high chance you overwrite commits from your colleagues, resulting in lost work;
- There’s a high chance your colleagues will be developing their work based on the old commit history.
In short, even if you get away with Force Pushing once or twice, it’s only a matter of time until something goes wrong. Time to look for an alternative!
Force with Lease — a safer alternative
To make sure you don’t ever overwrite your teammate’s commits, you can have a look at --force-with-lease flag, which is essentially a safer, lesser-known, option.
If somebody has updated the branch upstream while you were working on something, you can rest assured that everything will be intact, as the command will fail and prompt you to fetch first. This way, everyone’s work is preserved.
In our Git client, this was integrated into Tower’s 6.3 release so that our users always have their seatbelts on!
Executing git push --force-with-lease by default is something we would recommend 99% of the time, but there are still situations where Force Pushing could make sense.
Let’s look into them now.
4. When Should I Use Force Push?
As a rule of thumb, you should only Force Push when you’re absolutely sure you know what you’re doing.
Here are a couple of scenarios where Force Push would make sense:
Scenario 1: Sensitive Information Uploaded to the Repo by Accident
You noticed there’s a file that contains sensitive information (eg: a password). You don’t want that information publicly accessible and you want to delete that file altogether. This happened 6 commits ago.
You could use Interactive Rebase to remove that commit from your project, and then you would have to Force Push it to the remote repository to make sure that it is deleted for everyone else when your colleagues update the local version via git pull.
This way, the sensitive information will eventually disappear. Please keep in mind that, if this was a pull request from someone else, that request will still be visible until the original author deleted it.
Scenario 2: You Don’t Want to Deal With Merge Conflicts
Things got messy, but the working version in your local machine is the one that should be going forward — you know it, and your team knows it. If you want to prioritize your local branch over the remote one, overwriting any commits made along the way, then by all means go for it.
In a less extreme situation, Force Pushing can still be appropriate. Sometimes we're simply working on a private branch that should not be used by anyone else. Before merging/moving to a branch that a group of people collaborate on, it may make sense to perform a little clean-up and force push (this is also a common use case for pull requests in open source projects).
As you can see, in some situations Force Pushing can be your friend. If you are using Tower, our Git client, the “force” flag is available as an option in Tower's Push dialog:
In conclusion, Force Push is a very powerful command in Git — we just have to make sure we use it with care (Tower will always warn you in case something risky is about to happen).
In this article, we have presented the risks of Force Pushing and scenarios where it is a necessity. We have also learned about a safer alternative (--force-with-lease) that you can default to on most occasions.
To learn how to recover (or prevent) disasters in the future, read our complete Force Push guide; then, you will officially become a Force Push ninja!