- Developers who already know basic commit and branch actions
- Readers who want to understand command boundaries and risk
Command Reference
git push Tutorial
Explains how git push publishes local branches, how upstream tracking works, and how to reason about safe versus risky publication.
- A basic mental model of worktree, index, and commits
- Comfort reading `git status` and a small commit graph
- Using local cleanup commands on already shared history
- Continuing to rewrite before confirming a recovery path
The short version
git push sends local refs and objects to a remote repository so other systems or teammates can see the new history.
The important shift is social, not only technical. Once you push, your local history may become part of review, CI, deployment, or another person's branch base.
What this command really changes
When people think about git push, they often focus on auth or syntax.
The more important question is:
what shared ref am I about to update?
That determines whether push is:
- harmless publication of a feature branch
- a routine update to a review branch
- a dangerous rewrite of a shared branch
Common forms
git push origin main
git push -u origin feature/login
git push --force-with-lease
git push origin main: update a named remote branchgit push -u origin feature/login: publish and set upstream trackinggit push --force-with-lease: rewrite remote history only if the remote tip still matches what you expect
When -u matters
Setting upstream once makes later commands simpler because the branch now knows which remote branch it tracks.
That improves:
git pushgit pullgit status
especially on new feature branches.
A safer push checklist
Before pushing, ask:
- am I targeting the intended remote and branch?
- is this branch shared, protected, or review-visible?
- am I publishing new commits or rewriting old ones?
- does the working tree and local history look the way I think they do?
A practical preflight is:
git status
git log --oneline --graph --decorate -8
git remote -v
Why --force-with-lease exists
There are cases where rewriting remote history is legitimate:
- cleaning up your own feature branch before merge
- updating a review branch after local history cleanup
- replacing a mistaken push that nobody else built on
But blind --force ignores whether the remote has moved since you last checked.
--force-with-lease is safer because it says:
“rewrite only if the remote tip is still the one I think it is.”
If you ever need to rewrite published history, --force-with-lease should be the default reflex. Raw --force should feel exceptional.
Diagram view
Local branch tipRemote branch tipRemote policy
Published commitsUpdated upstream refRejected or protected push
The most valuable push question is not “did it work?” It is “did I publish exactly the history I intended to publish?”
Common mistakes
- pushing to the wrong remote because
originwas assumed - pushing mixed or unreviewed commits too early
- rewriting a branch that teammates already pulled
- using force when the real problem was poor local branch hygiene
Once the target branch is used by teammates, CI, or deployment, push is no longer only your local action. It becomes part of system coordination.
Try it yourself
The goal is to understand the difference between first publication, later updates, and risky rewrites.
git switch -c lab/push-demo # create one or two local commitsTry it
- Run `git push -u origin lab/push-demo` on a throwaway branch.
- Inspect `git status` and notice the upstream relationship.
- Add another commit and run `git push` again.
- Then ask what would change if you had rewritten local history before the second push.
- You learn what first-time publication does differently from later updates.
- You see how upstream tracking simplifies normal sync flow.
- You build a stronger intuition for when a later push would become a rewrite decision.
- Verify the remote and branch before publishing if multiple remotes exist.
- Do not use force to fix unclear local history unless you have checked the remote impact.
- If a push is rejected, confirm whether the issue is auth, protection, or non-fast-forward history.