Do these 3 things before closing this tab:
1Repair Windows errors before they cause bigger problems2Scan for outdated or missing drivers - takes under a minute3Clear out junk files and repair common Windows errorsgit push sends the repository data a remote needs and asks it to update one or more refs—usually branches—to point to the commits you selected. Git first decides which remote and refs are involved, then transfers missing objects; the remote checks the proposed updates and either accepts or rejects them. Optional server hooks and policies can affect the outcome.
What a push changes—and what it does not
The Git project describes git push as updating branches, tags, or other references in a remote repository and sending necessary data the remote does not already have. A ref is a name, such as refs/heads/main, that points to a commit or another Git object. In a typical branch push, the key change is the remote branch ref moving to a commit already in your local history.
As an Amazon Associate I earn from qualifying purchases.
Git does not resend every file or every commit on each push. It transfers the objects needed for the requested refs that the remote lacks. The command concerns Git repository data and refs; a hosting platform’s build or deployment actions, if any, are separate platform behavior. See the Git 2.53.0 git-push manual.
How Git decides what to push
1. It selects a remote
You can name a remote, such as origin, or provide a URL. If you omit the repository argument, Git uses the current branch’s upstream when one is configured; otherwise, it uses origin.
#1 Best Overall
2. It selects and maps refs
Git determines what refs to push using this precedence: refspecs and options on the command line, then remote.<name>.push configuration, then push.default. The default push.default=simple pushes the current branch to a same-named branch, subject to its upstream relationship.
A refspec has the form [+]<src>[:<dst>]. The source is the local ref; the destination is the remote ref. For example, main:other maps local main to remote other. Writing just main normally means pushing to the same-named remote branch. Options can broaden or otherwise change the selection: --all selects branches, --tags selects tags, --mirror mirrors refs, and --follow-tags can include relevant annotated tags. A deletion refspec can request removal of a remote ref.
Rank #2
3. It transfers missing objects
After identifying the refs, Git sends the objects needed for their proposed values that are not already available on the remote. The exact transfer depends on what the remote already has, not simply on how many files or commits exist in your local repository.
Free tools Windows power users keep installed
One-click scans. No signup required.
What the remote does with the proposed update
The remote receive service can check updates before changing refs. On a server configured with hooks, an executable pre-receive hook runs once before refs are updated and may reject the push. An update hook runs separately for each ref and may reject an individual ref update. If updates succeed, configured post-receive and then post-update hooks can run. Hooks are optional; they are not guaranteed to run on every push.
For quarantine handling, incoming objects are initially placed in a quarantine directory and moved into the main object store after pre-receive succeeds. The receiving service and hooks are documented in the Git project’s git-receive-pack manual.
Why Git may refuse to update a branch
Fast-forward protection
An ordinary branch update must generally be a fast-forward: the remote branch’s current commit must be an ancestor of the commit you are pushing. That rule prevents a normal push from silently discarding remote history. If someone has pushed work you do not have, your update may be rejected as non-fast-forward. Integrate the remote work, then retry the normal push.
Force-with-lease
git push --force-with-lease permits a non-fast-forward update only if the remote ref still has the expected value. This is a guard against overwriting changes made since you last knew the remote state, not a substitute for understanding the history being rewritten. Use it only when rewriting published history is intentional and you have checked the expected remote state.
Atomic ref updates
git push --atomic asks the remote to update all requested refs as one transaction. If the remote supports atomic pushes, all requested updates succeed together or none do. If atomic updates are unsupported, the push fails rather than silently proceeding as a non-atomic update.
Best Value
Common push commands and their effects
| Command | What it selects or requests | Important behavior |
|---|---|---|
git push origin main |
Push local main to the configured remote named origin, normally to remote main. |
Subject to ordinary fast-forward and remote policy checks. |
git push |
Uses the configured default destination and push selection. | With standard defaults, destination comes from the current branch’s upstream or origin, and push.default=simple selects the same-named branch. |
git push -u origin <name> |
Pushes the named branch to origin. |
-u sets the upstream tracking reference for that branch, which affects later default pushes and pulls. |
git push --force-with-lease |
Pushes the selected refs while allowing a non-fast-forward update if the remote ref matches the expected value. | Can rewrite remote history; use only when that is intended. |
git push --tags |
Pushes tags rather than only the default branch selection. | Remote policies and hooks can still reject updates. |
These examples reflect the Git project’s Git Cheat Sheet and git-push manual.
Quick Recap
How to diagnose a rejected push
- Read the rejection message. A non-fast-forward rejection means the remote branch has history your proposed update does not preserve. A hook or policy rejection may instead identify a server rule, such as a prohibited ref update.
- For non-fast-forward, inspect and integrate remote work. Fetch or otherwise inspect the remote branch, reconcile its commits with your local work, and retry a normal push. Do not force-push simply to bypass the rejection.
- For hook or policy rejection, follow the stated rule. Review the remote’s feedback and repository policy; changing local history will not necessarily address a server-side restriction.
- Preview when appropriate.
git push --dry-runperforms the operation without actually sending updates, so you can check what Git intends to push. - If history rewriting is deliberate, use a lease carefully. Confirm the remote value you expect before using
--force-with-lease; another contributor’s newer work may otherwise be at risk.
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
