Git Course 0%

git push

Intermediate Git CLI Careful ≈ 7 min

Summary: git push uploads the commits on your current branch to the remote and moves the remote's branch to match. -u on the first push also links the two so later pushes need no arguments.

Careful — an ordinary push cannot lose anything: Git rejects any push that would discard commits. --force removes that protection and is Dangerous.

What it does

Sends the objects the remote lacks, then asks it to move the branch. The remote accepts only if the new commit is a descendant of the old one, so nothing already there is lost. Your local origin/<branch> bookmark is updated to match.

Why it exists

Commits are local until pushed. This is the step that makes work visible to colleagues, to the pipeline and to merge requests, and it is the backup.

When to use it

  • After finishing a piece of work, and at least at the end of every day.
  • To publish a new branch: -u origin <branch> the first time.
  • To delete a remote branch: --delete.
  • To publish tags: git push origin <tag> or --tags.

When not to use it

  • With --force on any branch other people use.
  • Instead of a merge request on a protected branch; it will be rejected anyway (lesson 6.9).

Syntax

Form Meaning
git push Push the current branch to its tracked remote branch
git push -u origin <branch> First push of a new branch; also sets the upstream
git push origin <branch> Push a named branch
git push origin --delete <branch> Delete the branch on the remote
git push origin <tag> / --tags Push one tag / all tags
git push --force-with-lease Replace the remote branch, refusing if someone pushed since your last fetch
git push --force Replace it unconditionally Dangerous

Examples

An ordinary push:

Terminal
$ git push
To https://gitlab.com/you/trailguide.git
   01268bf..127f39e  main -> main

Publishing a new branch:

Terminal
$ git push -u origin docs/33-faq-windows
To https://gitlab.com/you/trailguide.git
 * [new branch]      docs/33-faq-windows -> docs/33-faq-windows
branch 'docs/33-faq-windows' set up to track 'origin/docs/33-faq-windows'.

Without -u on a new branch, Git stops and prints the command to use:

Output
fatal: The current branch docs/12-windows-install-steps has no upstream branch.
To push the current branch and set the remote as upstream, use

    git push --set-upstream origin docs/12-windows-install-steps

Deleting a remote branch:

Terminal
$ git push origin --delete docs/33-faq-windows
To https://gitlab.com/you/trailguide.git
 - [deleted]         docs/33-faq-windows

The rejection that protects a colleague's commits:

Output
 ! [rejected]        main -> main (non-fast-forward)
error: failed to push some refs to 'https://gitlab.com/northwind-trails/trailguide.git'
hint: Updates were rejected because the tip of your current branch is behind
hint: its remote counterpart. If you want to integrate the remote changes,
hint: use 'git pull' before pushing again.

And the platform's own refusal on a protected branch, which no amount of pulling fixes:

Output
remote: GitLab: You are not allowed to push code to protected branches on this project.
To https://gitlab.com/northwind-trails/trailguide.git
 ! [remote rejected] main -> main (pre-receive hook declined)

After a deliberate rebase of your own branch:

Terminal
$ git push --force-with-lease
To https://gitlab.com/northwind-trails/trailguide.git
 + 510f1e0...5f181fc docs/12-windows-install-steps -> docs/12-windows-install-steps (forced update)

Expected result

The remote branch moves to your commit, the output shows the range or * [new branch], and git status reports you are up to date. Nothing local changes except the origin/… bookmark.

Common mistakes

  • no upstream branch on the first push. Use -u once, or set push.autoSetupRemote true (lesson 3.5).
  • --force after a normal rejection. That rejection usually means a colleague pushed; forcing deletes their commits. Pull instead.
  • Confusing [rejected] with [remote rejected]. The first is Git's fast-forward check, the second the platform's rule (lesson 7.6).
  • Expecting push to send uncommitted work. It sends commits only.
  • Forgetting that push does not create a merge request. The platform prints a link; the merge request is a separate action.

How to undo or recover

  • A pushed commit that is wrong: git revert and push again; do not rewrite shared history.
  • A force push that destroyed a colleague's commits: their local clone still has them, and your git reflog has the previous remote position. Restore and push again with --force-with-lease, then tell the team (lesson 12.8).
  • A branch deleted on the remote by mistake: push it again from your local copy, if you still have it.

In VS Code

… menu → Push, or the sync button (pull then push). Publish Branch appears for a branch that has never been pushed. Force push must be enabled in Settings and should be paired with Git: Use Force Push With Lease.

In IntelliJ IDEA

Git → Push (Ctrl+Shift+K / ⇧⌘K) shows exactly which commits will be sent before you confirm; the dialog offers Force Push when the branch has diverged, using --force-with-lease.

git pull is the other direction and the fix for most rejections · git fetch shows what is on the remote first · git branch and git tag create what you push · git remote decides where it goes.

Lessons that use this command

Publish, track, update from main · When someone pushed before you · clone, remote, fetch, pull, push · Lab 2 · Lab 3.

Key terms

Push Remote origin Tracking branch (upstream) Protected branch

Related