Skip to main content

​
Synopsis

git push [--all | --branches | --mirror | --tags] [--follow-tags] [--atomic] 
         [-n | --dry-run] [--receive-pack=<git-receive-pack>]
         [--repo=<repository>] [-f | --force] [-d | --delete] [--prune] 
         [-q | --quiet] [-v | --verbose] [-u | --set-upstream] 
         [-o <string> | --push-option=<string>]
         [--[no-]signed | --signed=(true|false|if-asked)]
         [--force-with-lease[=<refname>[:<expect>]] [--force-if-includes]]
         [--no-verify] [<repository> [<refspec>...]]

​
Description

Updates one or more branches, tags, or other references in a remote repository from your local repository, and sends all necessary data that isn’t already on the remote. The simplest way to push is git push <remote> <branch>. git push origin main will push the local main branch to the main branch on the remote named origin. The <repository> argument defaults to the upstream for the current branch, or origin if there’s no configured upstream.

​
How Git Decides What to Push

To decide which branches, tags, or other refs to push, Git uses (in order of precedence):
  1. The <refspec> argument(s) (for example main in git push origin main) or the --all, --mirror, or --tags options
  2. The remote.<name>.push configuration for the repository being pushed to
  3. The push.default configuration. The default is push.default=simple, which will push to a branch with the same name as the current branch.
git push may fail if you haven’t set an upstream for the current branch, depending on what push.default is set to.

​
Common Usage

1

Push to the default remote

Push the current branch to its configured upstream:
git push
Works like git push <remote>, where <remote> is the current branch’s remote (or origin, if no remote is configured for the current branch).
2

Push a specific branch

Push the main branch to the origin remote:
git push origin main
This finds a ref that matches main in the source repository (most likely refs/heads/main), and updates the same ref in the origin repository. If main did not exist remotely, it would be created.
3

Set upstream and push

For every branch that is up to date or successfully pushed, add upstream (tracking) reference:
git push -u origin main
The -u flag sets the upstream for argument-less git pull and other commands.

​
Options

<repository>The “remote” repository that is the destination of a push operation. This parameter can be either a URL or the name of a remote.<refspec>...Specify what destination ref to update with what source object.The format for a refspec is [+]<src>[:<dst>], for example main, main:other, or HEAD^:refs/heads/main.
  • The <src> is often the name of the local branch to push, but it can be any arbitrary “SHA-1 expression”
  • The <dst> determines what ref to update on the remote side. It must be the name of a branch, tag, or other ref, not an arbitrary expression
  • The + is optional and does the same thing as --force
Special refspec forms:
  • <src> without a :<dst> means to update the same ref as the <src>
  • : (or +:) directs Git to push “matching” branches
  • <src> may contain a * to indicate a simple pattern match (e.g., refs/heads/*:refs/heads/*)
  • A refspec starting with ^ is a negative refspec to exclude refs
  • If <src> is empty, it deletes the <dst> ref from the remote repository (e.g., git push origin :dev deletes the dev branch)
  • tag <tag> expands to refs/tags/<tag>:refs/tags/<tag>
--all, --branchesPush all branches (i.e. refs under refs/heads/); cannot be used with other <refspec>.--tagsAll refs under refs/tags are pushed, in addition to refspecs explicitly listed on the command line.--follow-tagsPush all the refs that would be pushed without this option, and also push annotated tags in refs/tags that are missing from the remote but are pointing at commit-ish that are reachable from the refs being pushed.--mirrorInstead of naming each ref to push, specifies that all refs under refs/ be mirrored to the remote repository. Newly created local refs will be pushed to the remote end, locally updated refs will be force updated on the remote end, and deleted refs will be removed from the remote end.
-f, --forceUsually, git push will refuse to update a branch that is not an ancestor of the commit being pushed. This flag disables that check and can cause the remote repository to lose commits; use it with care.
Note that --force applies to all the refs that are pushed, hence using it with push.default set to matching or with multiple push destinations may overwrite refs other than the current branch.
--force-with-lease[=<refname>[:<expect>]]Usually, git push refuses to update a remote ref that is not an ancestor of the local ref used to overwrite it.This option overrides this restriction if the current value of the remote ref is the expected value. git push fails otherwise.This is a safer alternative to --force because it ensures you don’t accidentally overwrite someone else’s work. It’s like taking a “lease” on the ref without explicitly locking it, and the remote ref is updated only if the “lease” is still valid.--force-if-includesForce an update only if the tip of the remote-tracking ref has been integrated locally. This option enables a check that verifies if the tip of the remote-tracking ref is reachable from one of the “reflog” entries of the local branch.
-d, --deleteAll listed refs are deleted from the remote repository. This is the same as prefixing all refs with a colon.--pruneRemove remote branches that don’t have a local counterpart. For example, a remote branch tmp will be removed if a local branch with the same name doesn’t exist any more.
-n, --dry-runDo everything except actually send the updates.-q, --quietSuppress all output, including the listing of updated refs, unless an error occurs. Progress is not reported to the standard error stream.-v, --verboseRun verbosely.--porcelainProduce machine-readable output. The output status line for each ref will be tab-separated and sent to stdout instead of stderr.
-u, --set-upstreamFor every branch that is up to date or successfully pushed, add upstream (tracking) reference, used by argument-less git pull and other commands.--verify, --no-verifyToggle the pre-push hook. The default is --verify, giving the hook a chance to prevent the push. With --no-verify, the hook is bypassed completely.
--atomic, --no-atomicUse an atomic transaction on the remote side if available. Either all refs are updated, or on error, no refs are updated. If the server does not support atomic pushes the push will fail.-o <option>, --push-option=<option>Transmit the given string to the server, which passes them to the pre-receive as well as the post-receive hook.--signed=(true|false|if-asked)GPG-sign the push request to update refs on the receiving side, to allow it to be checked by the hooks and/or be logged.--recurse-submodules=(check|on-demand|only|no)May be used to make sure all submodule commits used by the revisions to be pushed are available on a remote-tracking branch.

​
Examples

​
Push current branch to default remote

$ git push
Works like git push <remote>, where <remote> is the current branch’s remote (or origin, if no remote is configured for the current branch).

​
Push to origin with same branch name

$ git push origin
Without additional configuration, pushes the current branch to the configured upstream if it has the same name as the current branch, and errors out without pushing otherwise.

​
Push a specific branch

$ git push origin master
Find a ref that matches master in the source repository (most likely refs/heads/master), and update the same ref in origin repository with it. If master did not exist remotely, it would be created.

​
Push and set upstream

$ git push -u origin feature-branch
Push the feature-branch to origin and set it as the upstream branch for future pushes and pulls.

​
Push current branch to remote with different name

$ git push origin HEAD:master
Push the current branch to the remote ref matching master in the origin repository. This form is convenient to push the current branch without thinking about its local name.

​
Create a new remote branch with different name

$ git push origin master:refs/heads/experimental
Create the branch experimental in the origin repository by copying the current master branch. This form is only needed to create a new branch or tag in the remote repository when the local name and the remote name are different.

​
Delete a remote branch

$ git push origin :experimental
# or
$ git push origin --delete experimental
Find a ref that matches experimental in the origin repository (e.g. refs/heads/experimental), and delete it.

​
Force push with lease (safer)

$ git push --force-with-lease origin main
This is a safer alternative to --force because it will only succeed if nobody else has pushed to the branch since you last fetched.

​
Push all branches

$ git push --all origin
Push all branches to the origin remote.

​
Dry run to see what would be pushed

$ git push --dry-run origin
Show what would be pushed without actually sending the updates.

​
Push Rules

As a safety feature, the git push command only allows certain kinds of updates to prevent you from accidentally losing data on the remote. Because branches and tags are intended to be used differently, the safety rules for pushing to a branch are different from the rules for pushing to a tag:
  1. If the push destination is a branch (refs/heads/*): only fast-forward updates are allowed, which means the destination must be an ancestor of the source commit. The source must be a commit.
  2. If the push destination is a tag (refs/tags/*): all updates will be rejected. The source can be any object.
  3. If the push destination is not a branch or tag: specific rules apply for tree, blob, tag, and commit objects.
You can override these rules by passing --force or by adding the optional leading + to a refspec. The only exceptions are that no amount of forcing will make a branch accept a non-commit object, and forcing won’t make the remote repository accept a push that it’s configured to deny.

​
Note About Fast-Forwards

When an update changes a branch (or more in general, a ref) that used to point at commit A to point at another commit B, it is called a fast-forward update if and only if B is a descendant of A. In a fast-forward update from A to B, the set of commits that the original commit A built on top of is a subset of the commits the new commit B builds on top of. Hence, it does not lose any history. In contrast, a non-fast-forward update will lose history. For example, suppose you and somebody else started at the same commit X, and you built a history leading to commit B while the other person built a history leading to commit A: 
      B
     /
 ---X---A
The command by default does not allow an update that is not a fast-forward to prevent such loss of history. If you do not want to lose your work (history from X to B) or the work by the other person (history from X to A), you would need to first fetch the history from the repository, create a history that contains changes done by both parties, and push the result back. You can perform git pull, resolve potential conflicts, and git push the result. A git pull will create a merge commit C between commits A and B: 
      B---C
     /   /
 ---X---A
Alternatively, you can rebase your change between X and B on top of A, with git pull --rebase, and push the result back.

git pull

Fetch from and integrate with another repository

git fetch

Download objects and refs from another repository

git remote

Manage set of tracked repositories

git config

Get and set repository or global options

Build docs developers (and LLMs) love

Get started for freeTalk to us