![[tokkee]](http://tokkee.org/images/avatar.png){kind=avatar}
index 6150b1b959e17655a2875d39ec3b70449684a0eb..52c0538df528ecbb5b755a2e75fc1715762bfc00 100644 (file)
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. See the section <<URLS,GIT URLS>> below.
+ operation. This parameter can be either a URL
+ (see the section <<URLS,GIT URLS>> below) or the name
+ 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> (or, if no <dst> was
-specified, the same ref that <src> referred to locally). 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 parameter <ref> without a colon pushes the <ref> from the source
-repository to the destination repository under the same name.
+`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)
-directs git to push "matching" heads: for every head that exists on
-the local side, the remote side is updated if a head of the same name
+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 no explicit refspec is found (that is neither on the command line
nor in any Push line of the corresponding remotes file---see below).
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
line.
--receive-pack=<git-receive-pack>::
+--exec=<git-receive-pack>::
Path to the 'git-receive-pack' program on the remote
end. Sometimes useful when pushing to a remote
repository over ssh, and you do not have the program in
a directory on the default $PATH.
---exec=<git-receive-pack>::
- Same as \--receive-pack=<git-receive-pack>.
-
-f::
--force::
Usually, the command refuses to update a remote ref that is
--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