Pages

Topics

Tools

↑↓navigate↵openescclose
All guides

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.

~5 min readGit
#Git#Push#Remote#Release
3D illustration of a local repository cube pushing commit blocks through a locked lease gate to a remote cube

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

bash
# 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 true

push.default decides what a bare git push sends:

ValuePushesTypical use
simple (default)Current branch to same-named upstreamEvery normal workflow
currentCurrent branch to same-named remote branchBranch-per-feature servers
upstream / trackingCurrent branch to its upstream, even a differently named onelocal → origin/dev
matchingEvery branch that exists on both sidesLegacy; surprising on shared remotes
nothingRefuses without a refspecRepositories where a mistake is expensive

Key Comparison Table

FlagChecks remote stateCan overwrite unseen commitsWorks when remote movedSafe on shared branch
git pushYes, fast-forward ruleNoRejected, fetch and integrateYes
--forceNoYes, alwaysYesNo
--force-with-leaseAgainst origin/<branch>Yes, if that ref is staleOnly if tracking ref matchesWith the pinned form
--force-with-lease=<ref>:<sha>Against an exact commitNoRejected unless unchangedYes
--force-if-includesAgainst your reflogNoRejected until you mergeYes, with lease
--mirrorNoDeletes remote refs tooYesNever outside a backup
OperationRef touchedNeeds the object locallyReversible by
push origin mainrefs/heads/mainCommit reachable from mainNormal history rules
push origin v2.1.0refs/tags/v2.1.0Tag object and targetRe-creating the tag, force
push --delete feature/xRemoves refs/heads/feature/xNoRe-push the branch
push --atomicAll listed refsAll of themNothing partial happened

Practical Edge Cases and Deep Dives

1. The lease that silently passes

bash
# 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 commit

The 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:

bash
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.

bash
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>:main

GitHub 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

bash
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

bash
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

bash
git push origin main release/2.1 v2.1.0 git push --atomic origin main v2.1.0 # either both refs move or neither

Without --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

bash
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/x

git 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

SymptomCauseFix
! [rejected] main -> main (non-fast-forward)Remote moved, no forcegit fetch, review, merge or rebase
! [rejected] ... (stale info)--force-with-lease expected a different tipgit fetch and re-run, or pin the hash you expect
Colleague's commits vanished from main--force or a lease comparing a refreshed tracking refRestore from their reflog or a clone, then force back
remote: error: GH006: Protected branch update failedBranch protection on the targetOpen a pull request instead of pushing
refusing to delete the current branchServer's checked-out branchChange the server's HEAD first, or delete locally only
src refspec main does not match anyNo local commit yet, or typoCheck git branch --show-current
Tag push silently missing--tags not used and tag is lightweightgit push origin refs/tags/<name>
dst refspec matches more than oneBranch and tag share a nameUse refs/heads/... or refs/tags/...
--atomic rejected as unsupportedServer lacks the capabilityPush sequentially, or delete the pushed tag before retrying

Try matching browser tools

All tools

Small utilities that fit Git work — they run entirely in this browser tab, so nothing you paste leaves your device.

All Git guides

More in Git

All Git guides

The guides filed next to this one in Git, in library order.