NAME
----
-git-push - Update remote refs along with associated objects.
+git-push - Update remote refs along with associated objects
SYNOPSIS
--------
-'git-push' [--all] [--tags] [--force] <repository> <refspec>...
+[verse]
+'git push' [--all | --mirror | --tags] [--dry-run] [--receive-pack=<git-receive-pack>]
+ [--repo=<repository>] [-f | --force] [-v | --verbose]
+ [<repository> <refspec>...]
DESCRIPTION
-----------
You can make interesting things happen to a repository
every time you push into it, by setting up 'hooks' there. See
-documentation for gitlink:git-receive-pack[1].
+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 `+`, followed
- by the source ref, followed by a colon `:`, followed by
- the destination ref.
+<refspec>...::
+ 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 can be an
-arbitrary "SHA1 expression" that can be used as an
-argument to `git-cat-file -t`. E.g. `master~4` (push
-four parents before the current master head).
+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 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.
+
-Note: 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), then all the
-refs that exist both on the local side and on the remote
-side are updated.
+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.
+
-Some short-cut notations are also supported.
+`tag <tag>` means the same as `refs/tags/<tag>:refs/tags/<tag>`.
+
-* `tag <tag>` means the same as `refs/tags/<tag>:refs/tags/<tag>`.
-* A parameter <ref> without a colon is equivalent to
- <ref>`:`<ref>, hence updates <ref> in the destination from <ref>
- in the source.
+Pushing an empty <src> allows you to delete the <dst> ref from
+the remote repository.
++
+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).
+
+--all::
+ Instead of naming each ref to push, specifies that all
+ refs under `$GIT_DIR/refs/heads/` be pushed.
-\--all::
+--mirror::
Instead of naming each ref to push, specifies that all
- refs be pushed.
+ refs under `$GIT_DIR/refs/` (which includes but is not
+ limited to `refs/heads/`, `refs/remotes/`, and `refs/tags/`)
+ 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. This is the default
+ if the configuration option `remote.<remote>.mirror` is
+ set.
-\--tags::
+--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.
--f, \--force::
+--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.
+
+-f::
+--force::
Usually, the command refuses to update a remote ref that is
- not a descendent of the local ref used to overwrite it.
+ not an ancestor of the local ref used to overwrite it.
This flag disables the check. This can cause the
remote repository to lose commits; use it with care.
-include::urls.txt[]
+--repo=<repository>::
+ This option is only relevant if no <repository> argument is
+ passed in the invocation. In this case, 'git-push' derives the
+ remote name from the current branch: If it tracks a remote
+ branch, then that remote repository is pushed to. Otherwise,
+ the name "origin" is used. For this latter case, this option
+ can be used to override the name "origin". In other words,
+ the difference between these two commands
++
+--------------------------
+git push public #1
+git push --repo=public #2
+--------------------------
++
+is that #1 always pushes to "public" whereas #2 pushes to "public"
+only if the current branch does not track a remote branch. This is
+useful if you write an alias or script around 'git-push'.
+
+--thin::
+--no-thin::
+ These options are passed to 'git-send-pack'. Thin
+ transfer spends extra cycles to minimize the number of
+ objects to be sent and meant to be used on slower connection.
+
+-v::
+--verbose::
+ Run verbosely.
+
+include::urls-remotes.txt[]
+
+OUTPUT
+------
+
+The output of "git push" depends on the transport method used; this
+section describes the output when pushing over the git protocol (either
+locally or via ssh).
+
+The status of the push is output in tabular form, with each line
+representing the status of a single ref. Each line is of the form:
+
+-------------------------------
+ <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
+ rejected or failed to push, and '=' for a ref that was up to
+ date and did not need pushing (note that the status of up to
+ date refs is shown only when `git push` is running verbosely).
+
+summary::
+ 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
+ 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
+ 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
+ remote end did not report the successful update of the ref
+ (perhaps because of a temporary error on the remote side, a
+ break in the network connection, or other transient error).
+
+from::
+ The name of the local ref being pushed, minus its
+ `refs/<type>/` prefix. In the case of deletion, the
+ name of the local ref is omitted.
+
+to::
+ The name of the remote ref being updated, minus its
+ `refs/<type>/` prefix.
+
+reason::
+ A human-readable explanation. In the case of successfully pushed
+ refs, no explanation is needed. For a failed ref, the reason for
+ failure is described.
+
+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
+ the same ref (e.g. `refs/heads/master`) in `origin` repository
+ with it. If `master` did not exist remotely, it would be
+ created.
+
+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`)
+ to update the ref that matches `satellite/master` (most probably
+ `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
+ needed to create a new branch or tag in the remote repository when
+ 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 <junkio@cox.net>
+Written by Junio C Hamano <gitster@pobox.com>, later rewritten in C
+by Linus Torvalds <torvalds@osdl.org>
Documentation
--------------
GIT
---
-Part of the gitlink:git[7] suite
-
+Part of the linkgit:git[1] suite