SYNOPSIS
--------
[verse]
-'git push' [--all | --mirror] [--dry-run] [--tags] [--receive-pack=<git-receive-pack>]
+'git push' [--all | --mirror | --tags] [-n | --dry-run] [--receive-pack=<git-receive-pack>]
[--repo=<repository>] [-f | --force] [-v | --verbose]
[<repository> <refspec>...]
documentation for linkgit:git-receive-pack[1].
-OPTIONS
--------
+OPTIONS[[OPTIONS]]
+------------------
<repository>::
The "remote" repository that is destination of a push
operation. This parameter can be either a URL
of a remote (see the section <<REMOTES,REMOTES>> below).
<refspec>...::
- The canonical format of a <refspec> parameter is
- `+?<src>:<dst>`; that is, an optional plus `{plus}`, followed
- by the source ref, followed by a colon `:`, followed by
- the destination ref.
+ The format of a <refspec> parameter is an optional plus
+ `{plus}`, followed by the source ref <src>, followed
+ by a colon `:`, followed by the destination ref <dst>.
+ It is used to specify with what <src> object the <dst> ref
+ in the remote repository is to be updated.
+
-The <src> side represents the source branch (or arbitrary
-"SHA1 expression", such as `master~4` (four parents before the
-tip of `master` branch); see linkgit:git-rev-parse[1]) that you
-want to push. The <dst> side represents the destination location.
+The <src> is often the name of the branch you would want to push, but
+it can be any arbitrary "SHA-1 expression", such as `master~4` or
+`HEAD` (see linkgit:git-rev-parse[1]).
+
-The local ref that matches <src> is used
-to fast forward the remote ref that matches <dst>. If
-the optional leading plus `+` is used, the remote ref is updated
-even if it does not result in a fast forward update.
+The <dst> tells which ref on the remote side is updated with this
+push. Arbitrary expressions cannot be used here, an actual ref must
+be named. If `:`<dst> is omitted, the same ref as <src> will be
+updated.
+
-`tag <tag>` means the same as `refs/tags/<tag>:refs/tags/<tag>`.
+The object referenced by <src> is used to update the <dst> reference
+on the remote side, but by default this is only allowed if the
+update can fast-forward <dst>. By having the optional leading `{plus}`,
+you can tell git to update the <dst> ref even when the update is not a
+fast-forward. This does *not* attempt to merge <src> into <dst>. See
+EXAMPLES below for details.
+
-A lonely <src> parameter (without a colon and a destination) pushes
-the <src> to the same name in the destination repository.
+`tag <tag>` means the same as `refs/tags/<tag>:refs/tags/<tag>`.
+
Pushing an empty <src> allows you to delete the <dst> ref from
the remote repository.
+
-The special refspec `:` (or `+:` to allow non-fast forward updates)
+The special refspec `:` (or `{plus}:` to allow non-fast-forward updates)
directs git to push "matching" branches: for every branch that exists on
the local side, the remote side is updated if a branch of the same name
already exists on the remote side. This is the default operation mode
if the configuration option `remote.<remote>.mirror` is
set.
+-n::
--dry-run::
Do everything except actually send the updates.
+--porcelain::
+ Produce machine-readable output. The output status line for each ref
+ will be tab-separated and sent to stdout instead of stderr. The full
+ symbolic names of the refs will be given.
+
--tags::
All refs under `$GIT_DIR/refs/tags` are pushed, in
addition to refspecs explicitly listed on the command
--verbose::
Run verbosely.
+-q::
+--quiet::
+ Suppress all output, including the listing of updated refs,
+ unless an error occurs.
+
include::urls-remotes.txt[]
OUTPUT
<flag> <summary> <from> -> <to> (<reason>)
-------------------------------
+If --porcelain is used, then each line of the output is of the form:
+
+-------------------------------
+ <flag> \t <from>:<to> \t <summary> (<reason>)
+-------------------------------
+
flag::
A single character indicating the status of the ref. This is
blank for a successfully pushed ref, `!` for a ref that was
For a successfully pushed ref, the summary shows the old and new
values of the ref in a form suitable for using as an argument to
`git log` (this is `<old>..<new>` in most cases, and
- `<old>...<new>` for forced non-fast forward updates). For a
+ `<old>...<new>` for forced non-fast-forward updates). For a
failed update, more details are given for the failure.
The string `rejected` indicates that git did not try to send the
- ref at all (typically because it is not a fast forward). The
+ ref at all (typically because it is not a fast-forward). The
string `remote rejected` indicates that the remote end refused
the update; this rejection is typically caused by a hook on the
remote side. The string `remote failure` indicates that the
refs, no explanation is needed. For a failed ref, the reason for
failure is described.
+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. The history looks like this:
+
+----------------
+
+ B
+ /
+ ---X---A
+
+----------------
+
+Further suppose that the other person already pushed changes leading to A
+back to the original repository you two obtained the original commit X.
+
+The push done by the other person updated the branch that used to point at
+commit X to point at commit A. It is a fast-forward.
+
+But if you try to push, you will attempt to update the branch (that
+now points at A) with commit B. This does _not_ fast-forward. If you did
+so, the changes introduced by commit A will be lost, because everybody
+will now start building on top of B.
+
+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) nor 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
+
+----------------
+
+Updating A with the resulting merge commit will fast-forward and your
+push will be accepted.
+
+Alternatively, you can rebase your change between X and B on top of A,
+with "git pull --rebase", and push the result back. The rebase will
+create a new commit D that builds the change between X and B on top of
+A.
+
+----------------
+
+ B D
+ / /
+ ---X---A
+
+----------------
+
+Again, updating A with this commit will fast-forward and your push will be
+accepted.
+
+There is another common situation where you may encounter non-fast-forward
+rejection when you try to push, and it is possible even when you are
+pushing into a repository nobody else pushes into. After you push commit
+A yourself (in the first picture in this section), replace it with "git
+commit --amend" to produce commit B, and you try to push it out, because
+forgot that you have pushed A out already. In such a case, and only if
+you are certain that nobody in the meantime fetched your earlier commit A
+(and started building on top of it), you can run "git push --force" to
+overwrite it. In other words, "git push --force" is a method reserved for
+a case where you do mean to lose history.
+
+
Examples
--------
+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).
+
+git push origin::
+ Without additional configuration, works like
+ `git push origin :`.
++
+The default behavior of this command when no <refspec> is given can be
+configured by setting the `push` option of the remote.
++
+For example, to default to pushing only the current branch to `origin`
+use `git config remote.origin.push HEAD`. Any valid <refspec> (like
+the ones in the examples below) can be configured as the default for
+`git push origin`.
+
+git push origin :::
+ Push "matching" branches to `origin`. See
+ <refspec> in the <<OPTIONS,OPTIONS>> section above for a
+ description of "matching" branches.
+
git push origin master::
Find a ref that matches `master` in the source repository
(most likely, it would find `refs/heads/master`), and update
with it. If `master` did not exist remotely, it would be
created.
-git push origin :experimental::
- Find a ref that matches `experimental` in the `origin` repository
- (e.g. `refs/heads/experimental`), and delete it.
+git push origin HEAD::
+ A handy way to push the current branch to the same name on the
+ remote.
git push origin master:satellite/master dev:satellite/dev::
Use the source ref that matches `master` (e.g. `refs/heads/master`)
`refs/remotes/satellite/master`) in the `origin` repository, then
do the same for `dev` and `satellite/dev`.
+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.
+
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
the local name and the remote name are different; otherwise,
the ref name on its own will work.
+git push origin :experimental::
+ Find a ref that matches `experimental` in the `origin` repository
+ (e.g. `refs/heads/experimental`), and delete it.
+
+git push origin {plus}dev:master::
+ Update the origin repository's master branch with the dev branch,
+ allowing non-fast-forward updates. *This can leave unreferenced
+ commits dangling in the origin repository.* Consider the
+ following situation, where a fast-forward is not possible:
++
+----
+ o---o---o---A---B origin/master
+ \
+ X---Y---Z dev
+----
++
+The above command would change the origin repository to
++
+----
+ A---B (unnamed branch)
+ /
+ o---o---o---X---Y---Z master
+----
++
+Commits A and B would no longer belong to a branch with a symbolic name,
+and so would be unreachable. As such, these commits would be removed by
+a `git gc` command on the origin repository.
+
+
Author
------
Written by Junio C Hamano <gitster@pobox.com>, later rewritten in C