Git Push Explained: Syntax, Examples, Errors & Best Practices

git push is used to upload your local commits to a remote repository, making your changes available to others. It updates remote branches, tags, or refs based on your local repository state. Understanding how and when to use git push is essential for safe and efficient collaboration in Git.

git push command - Quick Cheat Sheet

git push Syntax and Basic Usage

git push command syntax explained

The basic syntax of git push is:

git push [options] <remote> <branch>

• <remote>: Name of the remote repository (commonly origin)
• <branch>: The branch you want to push (e.g., main, dev)

Example:

git push origin main

This command pushes your local main branch to the remote repository named origin.

Understanding remote and origin in git

In Git, a remote refers to a version of your repository hosted elsewhere (such as GitHub, GitLab, or Bitbucket).

• origin is the default name given to the remote repository when you clone a project.
• You can have multiple remotes (e.g., origin, upstream).

To view configured remotes:

git remote -v

To add a new remote:

git remote add origin https://github.com/user/repo.git

So when you run:

git push origin main

You are pushing changes from your local main branch to the main branch of the remote repository named origin.

Default behavior when branch is not specified

If you run:

git push

Git behaves based on your configuration:

• If an upstream branch is already set, Git pushes the current branch to its tracked remote branch.
• If no upstream is set, Git will show an error and ask you to specify the remote and branch.

Example error:

fatal: The current branch dev has no upstream branch.

To fix this, set upstream:

git push -u origin dev

After this, you can simply use:

git push

Git will automatically push to the configured upstream branch.

Push Local Changes to Remote Repository

The most common use of the git push command is to upload your local commits to a remote repository so others can access your changes. In simple terms, git push takes everything you have committed locally and updates the remote branch with those changes.

Before using git push, make sure you have already added and committed your changes:

git add .
git commit -m "added new changes"

Now you can push your code to the remote repository.

The most widely used command is:

git push origin main

• origin → remote repository name
• main → branch name

This command pushes your local main branch to the remote main branch. This is one of the most searched patterns for git push example, git push origin, and git push command example.

Push current branch without specifying branch name

If your branch is already linked to a remote (upstream is set), you can simply run:

git push

Git will automatically push the current branch to its corresponding remote branch. This is commonly used in daily workflows and answers queries like how to git push and git push usage.

Push a new branch to remote

If you are working on a new branch and want to push it to the remote repository:

git push -u origin feature-branch

The -u (or --set-upstream) option sets the upstream tracking. After this, you can just use git push without specifying the branch again.

Push local branch to a different remote branch

You can also push your local branch to a differently named branch on the remote:

git push origin local-branch:remote-branch

Example:

git push origin dev:production

This pushes your local dev branch to the remote production branch.

Push changes to origin explicitly

Another commonly used variation is:

git push origin HEAD

This pushes the current branch (whatever you are working on) to the corresponding branch in the remote repository. It is useful when you don’t want to type the branch name manually.

First Time Push (Upstream Tracking)

When you push a branch for the first time, Git does not automatically know which remote branch it should track. This is where upstream tracking comes into play. Setting an upstream allows you to use simple commands like git push and git pull without specifying the remote and branch every time.

The most common command for first-time push is:

git push -u origin branch-name

Example:

git push -u origin feature-login

• -u (or --set-upstream) → links your local branch with the remote branch
• origin → remote repository
• feature-login → branch name

After running this once, Git remembers the relationship between your local and remote branch. Now you can simply use:

git push

To verify if upstream is set correctly:

git branch -vv

You will see your branch mapped to something like origin/feature-login.

If you forgot to set upstream during the first push, Git will show an error like:

fatal: The current branch feature-login has no upstream branch.

You can fix it using:

git push --set-upstream origin feature-login

Setting upstream tracking is important for efficient workflows, especially when working with multiple branches or collaborating with teams.

Force Push Safely

git push --force example (when to use)

Sometimes you may need to overwrite the remote branch history, especially after rewriting commits using rebase or amend. This is where force push is used, but it should be handled carefully to avoid losing other contributors' work.

Using force push:

git push --force

Example:

git push origin main --force

This command overwrites the remote main branch with your local branch. It is useful when you have rewritten history (for example using git rebase), but it can remove commits pushed by others.

git push --force-with-lease explained

A safer alternative is:

git push --force-with-lease

Example:

git push origin main --force-with-lease

This command ensures that the remote branch has not changed since your last fetch. If someone else has pushed new changes, the push will be rejected instead of overwriting their work.

Difference between force and force-with-lease

Key difference:

• --force → blindly overwrites remote history
• --force-with-lease → overwrites only if no new changes exist on remote

In most cases, you should prefer --force-with-lease as it provides a safer way to update remote branches without accidentally deleting others’ changes.

Working with Branches Using git push

Push new branch to remote

When working with multiple branches, git push helps you create, update, and remove branches on the remote repository.

To push a new branch to remote:

git push -u origin feature-branch

This creates the branch on the remote and sets upstream tracking so future pushes can be done using git push.

Delete remote branch using git push

To delete a remote branch:

git push origin --delete feature-branch

This removes the specified branch from the remote repository.

Older syntax (still valid):

git push origin :feature-branch

Rename and push branch

To rename a branch and push it:

git branch -m old-name new-name
git push origin new-name
git push origin --delete old-name

This sequence renames the local branch, pushes the new branch to remote, and deletes the old branch from the remote.

These operations are commonly used when managing feature branches, cleaning up old branches, or maintaining structured workflows.

Push Tags in Git

git push tag example

Git tags are used to mark important points in history, such as releases. You can push tags to a remote repository using git push.

To push a specific tag:

git push origin v1.0

This uploads the tag v1.0 to the remote repository.

Push all tags using --tags

To push all tags:

git push --tags

This pushes all local tags that are not yet available on the remote.

Delete remote tags

To delete a remote tag:

git push origin :refs/tags/v1.0

This removes the tag v1.0 from the remote repository.

Note:

• Deleting a tag locally does not remove it from the remote
• You must explicitly delete the tag on the remote

Working with tags is essential for versioning, release management, and tracking important milestones in your Git workflow.

Advanced git push Usage

Beyond basic usage, git push provides advanced capabilities that are useful in complex workflows such as multi-remote setups, controlled deployments, and repository mirroring.

Push to multiple remotes

To push to multiple remotes, you can define more than one remote repository and push changes individually:

git remote add upstream https://github.com/organization/repo.git
git push origin main
git push upstream main

This is useful when you want to keep multiple repositories in sync, such as pushing code to both a personal fork and an organization repository.

Push specific commits using refspec

You can also push specific commits or branches using refspec (reference specification):

git push origin local-branch:remote-branch

Example:

git push origin feature:release

This pushes your local feature branch to the remote release branch. Refspec gives you flexibility to map local and remote branches explicitly, which is helpful in CI/CD or deployment workflows.

Mirror repositories using --mirror

Another advanced option is mirroring the entire repository:

git push --mirror

This command pushes all refs (branches, tags, and deleted refs) to the remote, making it an exact copy of your local repository. It is commonly used for backups or migrations.

Important note:

• --mirror will overwrite the remote repository completely
• Use it carefully, especially in shared environments

Advanced git push usage is powerful but should be used with caution, as it directly affects remote repository structure and history.

Common git push Errors and Fixes

While using the git push command, you may encounter errors due to conflicts, outdated branches, or permission issues. Understanding these errors helps you quickly resolve problems and continue your workflow.

Error: failed to push some refs

This is one of the most common errors:

! [rejected] main -> main (non-fast-forward)
error: failed to push some refs

This happens when your local branch is behind the remote branch.

Fix:

git pull --rebase
git push

This ensures your local changes are updated with the latest remote commits before pushing. This error occurs when your git push is rejected because the remote branch has changes that are not present in your local repository.

Error: Updates were rejected (non-fast-forward)

Updates were rejected because the remote contains work that you do not have locally.

This means someone else has pushed changes to the same branch.

Fix:

git pull origin main
git push origin main

Or for cleaner history:

git pull --rebase origin main
git push

Error: Permission denied (authentication issue)

Permission denied (publickey).
fatal: Could not read from remote repository.

This occurs when SSH keys or authentication are not configured properly.

Fix:

• Verify SSH key:

ssh -T git@github.com

• Or switch to HTTPS remote:

git remote set-url origin https://github.com/user/repo.git

Error: rejected (stale info) with force-with-lease

! [rejected] (stale info)

This happens when using --force-with-lease and your local branch is outdated.

Fix:

git fetch
git push --force-with-lease

Error: src refspec does not match any

error: src refspec main does not match any

This usually means:

• Branch does not exist
• No commits have been made

Fix:

git add .
git commit -m "initial commit"
git push -u origin main

When to use force push

If you intentionally want to overwrite remote history:

git push --force

Safer alternative:

git push --force-with-lease

Use force push carefully, especially in shared repositories, as it can overwrite other developers’ changes.

Understanding these common git push errors, git push rejected scenarios, and git push fixes will help you troubleshoot issues quickly and use the git push command confidently.

Summary

The git push command is an essential part of Git workflows, allowing you to upload local changes to a remote repository. From basic usage like pushing branches to advanced scenarios such as force push, upstream tracking, and repository mirroring, understanding how git push works helps you collaborate effectively and manage code safely.

By following best practices and understanding common scenarios, you can use git push confidently in both individual and team environments.

Official Documentation

• Git Push Official Documentation