Git push: --force-with-lease, Tags, and Deleting Remote Branches
A lease compares against your tracking ref, so a background fetch can silently pass it. Pinning the hash or --force-if-includes closes the hole; tags need their own push.

Quick Summary
git push sends objects, then asks the server to move a ref. The ref update is fast-forward only unless you force it, and that rule is what protects other people's commits. --force disables the rule; --force-with-lease disables it only while the remote ref still matches what you last fetched, which is the correct tool for a rewritten branch.
The lease has one documented hole: it compares against your remote-tracking ref, not the actual remote. Anything that refreshes origin/main without you looking — an IDE's background fetch, a git fetch --all in another terminal — makes the lease expect the new value, so it will happily overwrite commits you never saw. Pinning the expected commit (--force-with-lease=main:<sha>) or adding --force-if-includes (Git 2.30+) closes it.
Deleting remote branches and tags is the same mechanism with an empty source: git push origin --delete feature/x is git push origin :feature/x. Tags are separate refs that a branch push does not carry, so a release needs its tag pushed explicitly or --follow-tags.
Basic Syntax and Core Signatures
# Normal push
git push # current branch to its upstream
git push -u origin main # set upstream (branch.main.merge)
git push origin HEAD:refs/heads/main # explicit destination
git push --dry-run # print what would happen
# Rewritten history
git push --force # overwrite, no questions
git push --force-with-lease # overwrite only if remote == origin/<branch>
git push --force-with-lease=main:9c1e2f4 # overwrite only if remote is exactly this
git push --force-if-includes # refuse if remote has commits you never merged
git push --force-with-lease --force-if-includes
# Delete
git push origin --delete feature/login
git push origin :feature/login # identical refspec form
git push origin --delete tag v1.0.0
git push origin :refs/tags/v1.0.0
# Tags
git push origin v2.1.0 # one tag
git push --tags # every local tag
git push --follow-tags # annotated tags reachable from pushed commits
git push --atomic origin main v2.1.0 # all refs or none
# Defaults
git config --global push.default simple
git config --global push.autoSetupRemote true # Git 2.37+: -u implicitly
git config --global push.followTags truepush.default decides what a bare git push sends:
| Value | Pushes | Typical use |
|---|---|---|
simple (default) | Current branch to same-named upstream | Every normal workflow |
current | Current branch to same-named remote branch | Branch-per-feature servers |
upstream / tracking | Current branch to its upstream, even a differently named one | local → origin/dev |
matching | Every branch that exists on both sides | Legacy; surprising on shared remotes |
nothing | Refuses without a refspec | Repositories where a mistake is expensive |
Key Comparison Table
| Flag | Checks remote state | Can overwrite unseen commits | Works when remote moved | Safe on shared branch |
|---|---|---|---|---|
git push | Yes, fast-forward rule | No | Rejected, fetch and integrate | Yes |
--force | No | Yes, always | Yes | No |
--force-with-lease | Against origin/<branch> | Yes, if that ref is stale | Only if tracking ref matches | With the pinned form |
--force-with-lease=<ref>:<sha> | Against an exact commit | No | Rejected unless unchanged | Yes |
--force-if-includes | Against your reflog | No | Rejected until you merge | Yes, with lease |
--mirror | No | Deletes remote refs too | Yes | Never outside a backup |
| Operation | Ref touched | Needs the object locally | Reversible by |
|---|---|---|---|
push origin main | refs/heads/main | Commit reachable from main | Normal history rules |
push origin v2.1.0 | refs/tags/v2.1.0 | Tag object and target | Re-creating the tag, force |
push --delete feature/x | Removes refs/heads/feature/x | No | Re-push the branch |
push --atomic | All listed refs | All of them | Nothing partial happened |
Practical Edge Cases and Deep Dives
1. The lease that silently passes
# 09:00 you fetch; origin/main = a1b2c3d
git fetch origin
# 09:30 a colleague pushes d4e5f6a to main
# 09:31 your editor's background fetch updates origin/main to d4e5f6a
git push --force-with-lease # compares against d4e5f6a: passes, deletes their commitThe lease is a comparison against a local ref, so "I have not seen the remote since" is an assumption, not a guarantee. Two reliable forms avoid it:
git push --force-with-lease=main:a1b2c3d origin main # fail unless remote is still a1b2c3d
git push --force-with-lease --force-if-includes origin main--force-if-includes is the better habit because it does not require you to keep a hash: it checks your reflog and refuses when the remote tip is not among the commits you have integrated. In practice it means "force only if I actually looked at what was there".
2. Undoing a force push
The remote's previous tip is in your reflog only if you had it. If the overwritten commits were never on your machine, the server's reflog is unreachable, and the honest answer is that recovery depends on someone's clone or the hosting provider.
git reflog show origin/main # remote-tracking history, if the lease compared and lost
git log --oneline --all --not main # commits that are now unreachable
git push --force-with-lease=main:<current> origin <recovered-sha>:mainGitHub additionally keeps the old ref visible in the repository's event and network views for a limited time, which is often the only route when a force push landed from a machine that then went offline.
3. Deleting a branch that refuses to go
git push origin --delete feature/login
# ! [remote rejected] feature/login (refusing to delete the current branch)Servers reject deleting the branch they have checked out (a bare repository hosting a site) and any branch matched by a protection rule. The refspec form is worth remembering because it composes: git push origin :refs/heads/feature/login works the same, and git push origin :refs/tags/v1.0.0 is the only way to delete a tag whose name also exists as a branch. Deleting a branch that is already gone fails with remote ref does not exist, so cleanup scripts should either check git ls-remote --heads origin first or accept the non-zero exit.
4. Tags do not travel with branches
git tag -a v2.1.0 -m "2.1.0"
git push origin main # tag NOT pushed
git push --follow-tags origin main # annotated tags reachable from main, pushed
git push origin v2.1.0 # explicit, unambiguous
git push --tags # every tag, including ones pointing at abandoned work--follow-tags only carries annotated tags, and only those reachable from the commits being pushed; lightweight tags are never followed. --tags is the opposite extreme and is how stray local experiment tags end up on a public mirror. A release job should push exactly the tag it built: git push origin main v${VERSION}. If the same name exists as a branch and a tag, git push origin v2.1.0 fails with dst refspec matches more than one; use the full ref, refs/tags/v2.1.0.
5. Multi-ref pushes and the atomic guarantee
git push origin main release/2.1 v2.1.0
git push --atomic origin main v2.1.0 # either both refs move or neitherWithout --atomic, each ref is a separate request and a hook rejection on the second leaves the first updated — a classic half-release where main is live but the tag is missing. Atomic pushes require server support (GitHub, GitLab, Gitea all provide it); on a server without it the push fails with the receiving end does not support --atomic push, which is a safe failure.
6. Upstream mismatches on a fork
git remote -v
# origin git@github.com:me/repo.git (my fork)
# upstream git@github.com:org/repo.git (the real repository)
git push -u origin feature/x # push to my fork, set upstream
git push --force-with-lease origin feature/xgit push with no arguments pushes to branch.<name>.remote, which after -u is origin. A branch cloned from upstream can therefore have branch.<name>.remote = upstream, and a force push aimed at your own fork silently targets the shared repository instead. git config --get branch.main.remote before any force push is cheap insurance; remote.pushDefault sets the destination independently of the tracking remote.
Common Git Operation Mistakes
| Symptom | Cause | Fix |
|---|---|---|
! [rejected] main -> main (non-fast-forward) | Remote moved, no force | git fetch, review, merge or rebase |
! [rejected] ... (stale info) | --force-with-lease expected a different tip | git fetch and re-run, or pin the hash you expect |
Colleague's commits vanished from main | --force or a lease comparing a refreshed tracking ref | Restore from their reflog or a clone, then force back |
remote: error: GH006: Protected branch update failed | Branch protection on the target | Open a pull request instead of pushing |
refusing to delete the current branch | Server's checked-out branch | Change the server's HEAD first, or delete locally only |
src refspec main does not match any | No local commit yet, or typo | Check git branch --show-current |
| Tag push silently missing | --tags not used and tag is lightweight | git push origin refs/tags/<name> |
dst refspec matches more than one | Branch and tag share a name | Use refs/heads/... or refs/tags/... |
--atomic rejected as unsupported | Server lacks the capability | Push sequentially, or delete the pushed tag before retrying |
Try matching browser tools
All toolsSmall utilities that fit Git work — they run entirely in this browser tab, so nothing you paste leaves your device.
Related Git guides
All Git guidesGit config: Aliases, rerere, and Credential Helpers
Five config scopes decide one value at a time. Aliases are user-level shorthand, rerere records conflict resolutions, and credential helpers choose where your secret lives.
Git Hooks: pre-commit, commit-msg, and Husky Automation
Hooks live in .git/hooks, which a clone never receives, so core.hooksPath and Husky are how they travel. Exit codes abort the operation, and every hook is bypassable.
Git bisect: Binary Search, Automated Scripts, and Bug Hunting
Mark one bad and one good commit and Git halves the range each step. bisect run automates it through exit codes, and monotonicity is the assumption that must hold.
Git ignore: Patterns, Negation, and Untracking Cached Files
Patterns are relative and last match wins, but a negation cannot revive a file inside an excluded directory. Ignore rules never touch tracked files: rm --cached first.
More in Git
All Git guidesThe guides filed next to this one in Git, in library order.