Skip to content
Tutorials Center
My learning

Topics

Git Reference ยท Remotes and Collaboration

git push --force-with-lease

Reference for git push --force-with-lease and --force-if-includes: overwrite a remote branch only if nobody else pushed since you last fetched. Compare it with --force.

After you amend, rebase or squash commits that are already on a remote, a normal push is rejected because the new history is not a fast-forward. git push --force overrides the check, but it also silently throws away any commits a colleague pushed to that branch since you last looked.

--force-with-lease is the safer form. It means: "force the update, but only if the remote branch still points where my remote-tracking branch says it does." If someone else pushed in the meantime, the push fails with "stale info" and nothing is lost.

Terminal
git push --force-with-lease[=<ref>[:<expect>]] [--force-if-includes] [<remote> [<branch>]]

Try it

Bash The lease protects a colleague's push

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

Bash Amend, then push with a lease

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

Syntax

Form Description
--force-with-lease For every ref being pushed, expect the remote value to equal your remote-tracking branch for it (for main, refs/remotes/origin/main).
--force-with-lease=<ref> Same check, limited to that ref; other refs are pushed without force.
--force-with-lease=<ref>:<expect> Expect the remote ref to be <expect> (a commit, or an empty value to require that the ref does not exist). Does not use tracking branches at all.
--force-if-includes In addition, require that your local branch has integrated the remote-tracking tip, according to its reflog.
--no-force-with-lease Cancel earlier lease options.

Configuration: none for the lease itself; it works with any push.default. Server side, receive.denyNonFastForwards and branch protection rules can still refuse the update.

Usage notes

  • The lease is only as good as your tracking branch. If something runs git fetch in the background (an editor, a cron job, an IDE), origin/main moves to the colleague's commit and the lease then passes even though you never saw those commits. This is the known weakness. Use --force-if-includes (Git 2.30+) to also check that you actually integrated the remote tip, or give an explicit <ref>:<expect> value.
  • With the explicit form --force-with-lease=main:<sha> no assumptions about tracking branches are made; script it after your own git rev-parse origin/main.
  • If the lease fails, run git fetch, look at what arrived (git log main..origin/main), rebase or merge, and push again.
  • Use it on your own feature branches after rebasing. Never rewrite shared branches such as main; branch protection on hosts should forbid force pushes there.
  • Plain --force still has uses (repairing a mirror, deleting a leaked secret after coordinating with the team), but it cannot be cancelled afterward except through reflogs on the server, which hosts often do not expose.
  • A leading + in a refspec (git push origin +main) forces just that ref; it is as unsafe as --force for it, so prefer the lease.
  • Combine with -n / --dry-run to see what would be overwritten.