git: git push force vs force with lease



~2 min read


386 words

When using git as a version control and rebasing, it’s quite easy to get into a state where your local has diverged from the remote in ways that necessitate overwriting the remote.

This happens because when you rebase git changes the hash for each commit and so the remote cannot reconcile your branch with the one it has.

The only thing you can do is overwrite the remote. Of course, this is potentially a dangerous operation. On this topic, the git documentation on rebasing is unequivocal its guidance:

Do not rebase commits that exist outside your repository and that people may have based work on.

If you follow that guideline, you’ll be fine. If you don’t, people will hate you, and you’ll be scorned by friends and family.

The good news is that pushing commits that are in conflict is not allowed by default. You need to explicitly say, “I know what I’m doing and I want to overwrite what you know about this branch with my own commits.”

This is what git push --force does.

Git push also has a lesser known option --force-with-lease which offers some additional protections - though is not full-proof. (I use it as a default at this point and have aliased the command as gpfwl in my .zshrc because of my reliance on it.)

What protections does --force-with-lease relative --force?

The protection it offers over --force is ensuring that subsequent changes your work wasn’t based on aren’t clobbered, but this is trivially defeated if some background process is updating refs in the background. We don’t have anything except the remote tracking info to go by as a heuristic for refs you’re expected to have seen & are willing to clobber.

The “lease” in “force-with-lease” is a reference to ref taken when origin was fetched and on which you’re rebasing. If that ref is still valid, the force-with-lease will be accepted. If it’s not, it’s rejected.

Effectively, this means that if your team hasn’t broken the lease by rebasing and pushing different changes, your push will be accepted. If they have, then your changes will be rejected and you’ll save yourself a headache of overwriting your teammates contributions.


Hi there and thanks for reading! My name's Stephen. I live in Chicago with my wife, Kate, and dog, Finn. Want more? See about and get in touch!