Documentation/git-push.txt

   1 git-push(1)
   2 ===========
   3
   4 NAME
   5 ----
   6 git-push - Update remote refs along with associated objects
   7
   8
   9 SYNOPSIS
  10 --------
  11 [verse]
  12 'git push' [--all | --mirror] [--dry-run] [--tags] [--receive-pack=<git-receive-pack>]
  13            [--repo=<repository>] [-f | --force] [-v | --verbose]
  14            [<repository> <refspec>...]
  15
  16 DESCRIPTION
  17 -----------
  18
  19 Updates remote refs using local refs, while sending objects
  20 necessary to complete the given refs.
  21
  22 You can make interesting things happen to a repository
  23 every time you push into it, by setting up 'hooks' there.  See
  24 documentation for linkgit:git-receive-pack[1].
  25
  26
  27 OPTIONS
  28 -------
  29 <repository>::
  30         The "remote" repository that is destination of a push
  31         operation.  See the section <<URLS,GIT URLS>> below.
  32
  33 <refspec>...::
  34         The canonical format of a <refspec> parameter is
  35         `+?<src>:<dst>`; that is, an optional plus `{plus}`, followed
  36         by the source ref, followed by a colon `:`, followed by
  37         the destination ref.
  38 +
  39 The <src> side represents the source branch (or arbitrary
  40 "SHA1 expression", such as `master~4` (four parents before the
  41 tip of `master` branch); see linkgit:git-rev-parse[1]) that you
  42 want to push.  The <dst> side represents the destination location.
  43 +
  44 The local ref that matches <src> is used
  45 to fast forward the remote ref that matches <dst> (or, if no <dst> was
  46 specified, the same ref that <src> referred to locally).  If
  47 the optional leading plus `+` is used, the remote ref is updated
  48 even if it does not result in a fast forward update.
  49 +
  50 `tag <tag>` means the same as `refs/tags/<tag>:refs/tags/<tag>`.
  51 +
  52 A parameter <ref> without a colon pushes the <ref> from the source
  53 repository to the destination repository under the same name.
  54 +
  55 Pushing an empty <src> allows you to delete the <dst> ref from
  56 the remote repository.
  57 +
  58 The special refspec `:` (or `+:` to allow non-fast forward updates)
  59 directs git to push "matching" heads: for every head that exists on
  60 the local side, the remote side is updated if a head of the same name
  61 already exists on the remote side.  This is the default operation mode
  62 if no explicit refspec is found (that is neither on the command line
  63 nor in any Push line of the corresponding remotes file---see below).
  64
  65 --all::
  66         Instead of naming each ref to push, specifies that all
  67         refs under `$GIT_DIR/refs/heads/` be pushed.
  68
  69 --mirror::
  70         Instead of naming each ref to push, specifies that all
  71         refs under `$GIT_DIR/refs/` (which includes but is not
  72         limited to `refs/heads/`, `refs/remotes/`, and `refs/tags/`)
  73         be mirrored to the remote repository.  Newly created local
  74         refs will be pushed to the remote end, locally updated refs
  75         will be force updated on the remote end, and deleted refs
  76         will be removed from the remote end.  This is the default
  77         if the configuration option `remote.<remote>.mirror` is
  78         set.
  79
  80 --dry-run::
  81         Do everything except actually send the updates.
  82
  83 --tags::
  84         All refs under `$GIT_DIR/refs/tags` are pushed, in
  85         addition to refspecs explicitly listed on the command
  86         line.
  87
  88 --receive-pack=<git-receive-pack>::
  89         Path to the 'git-receive-pack' program on the remote
  90         end.  Sometimes useful when pushing to a remote
  91         repository over ssh, and you do not have the program in
  92         a directory on the default $PATH.
  93
  94 --exec=<git-receive-pack>::
  95         Same as \--receive-pack=<git-receive-pack>.
  96
  97 -f::
  98 --force::
  99         Usually, the command refuses to update a remote ref that is
 100         not an ancestor of the local ref used to overwrite it.
 101         This flag disables the check.  This can cause the
 102         remote repository to lose commits; use it with care.
 103
 104 --repo=<repository>::
 105         This option is only relevant if no <repository> argument is
 106         passed in the invocation. In this case, 'git-push' derives the
 107         remote name from the current branch: If it tracks a remote
 108         branch, then that remote repository is pushed to. Otherwise,
 109         the name "origin" is used. For this latter case, this option
 110         can be used to override the name "origin". In other words,
 111         the difference between these two commands
 112 +
 113 --------------------------
 114 git push public         #1
 115 git push --repo=public  #2
 116 --------------------------
 117 +
 118 is that #1 always pushes to "public" whereas #2 pushes to "public"
 119 only if the current branch does not track a remote branch. This is
 120 useful if you write an alias or script around 'git-push'.
 121
 122 --thin::
 123 --no-thin::
 124         These options are passed to 'git-send-pack'.  Thin
 125         transfer spends extra cycles to minimize the number of
 126         objects to be sent and meant to be used on slower connection.
 127
 128 -v::
 129 --verbose::
 130         Run verbosely.
 131
 132 include::urls-remotes.txt[]
 133
 134 OUTPUT
 135 ------
 136
 137 The output of "git push" depends on the transport method used; this
 138 section describes the output when pushing over the git protocol (either
 139 locally or via ssh).
 140
 141 The status of the push is output in tabular form, with each line
 142 representing the status of a single ref. Each line is of the form:
 143
 144 -------------------------------
 145  <flag> <summary> <from> -> <to> (<reason>)
 146 -------------------------------
 147
 148 flag::
 149         A single character indicating the status of the ref. This is
 150         blank for a successfully pushed ref, `!` for a ref that was
 151         rejected or failed to push, and '=' for a ref that was up to
 152         date and did not need pushing (note that the status of up to
 153         date refs is shown only when `git push` is running verbosely).
 154
 155 summary::
 156         For a successfully pushed ref, the summary shows the old and new
 157         values of the ref in a form suitable for using as an argument to
 158         `git log` (this is `<old>..<new>` in most cases, and
 159         `<old>...<new>` for forced non-fast forward updates). For a
 160         failed update, more details are given for the failure.
 161         The string `rejected` indicates that git did not try to send the
 162         ref at all (typically because it is not a fast forward). The
 163         string `remote rejected` indicates that the remote end refused
 164         the update; this rejection is typically caused by a hook on the
 165         remote side. The string `remote failure` indicates that the
 166         remote end did not report the successful update of the ref
 167         (perhaps because of a temporary error on the remote side, a
 168         break in the network connection, or other transient error).
 169
 170 from::
 171         The name of the local ref being pushed, minus its
 172         `refs/<type>/` prefix. In the case of deletion, the
 173         name of the local ref is omitted.
 174
 175 to::
 176         The name of the remote ref being updated, minus its
 177         `refs/<type>/` prefix.
 178
 179 reason::
 180         A human-readable explanation. In the case of successfully pushed
 181         refs, no explanation is needed. For a failed ref, the reason for
 182         failure is described.
 183
 184 Examples
 185 --------
 186
 187 git push origin master::
 188         Find a ref that matches `master` in the source repository
 189         (most likely, it would find `refs/heads/master`), and update
 190         the same ref (e.g. `refs/heads/master`) in `origin` repository
 191         with it.  If `master` did not exist remotely, it would be
 192         created.
 193
 194 git push origin :experimental::
 195         Find a ref that matches `experimental` in the `origin` repository
 196         (e.g. `refs/heads/experimental`), and delete it.
 197
 198 git push origin master:satellite/master dev:satellite/dev::
 199         Use the source ref that matches `master` (e.g. `refs/heads/master`)
 200         to update the ref that matches `satellite/master` (most probably
 201         `refs/remotes/satellite/master`) in the `origin` repository, then
 202         do the same for `dev` and `satellite/dev`.
 203
 204 git push origin master:refs/heads/experimental::
 205         Create the branch `experimental` in the `origin` repository
 206         by copying the current `master` branch.  This form is only
 207         needed to create a new branch or tag in the remote repository when
 208         the local name and the remote name are different; otherwise,
 209         the ref name on its own will work.
 210
 211 Author
 212 ------
 213 Written by Junio C Hamano <gitster@pobox.com>, later rewritten in C
 214 by Linus Torvalds <torvalds@osdl.org>
 215
 216 Documentation
 217 --------------
 218 Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>.
 219
 220 GIT
 221 ---
 222 Part of the linkgit:git[1] suite