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 --exec=<git-receive-pack>::
  90         Path to the 'git-receive-pack' program on the remote
  91         end.  Sometimes useful when pushing to a remote
  92         repository over ssh, and you do not have the program in
  93         a directory on the default $PATH.
  94
  95 -f::
  96 --force::
  97         Usually, the command refuses to update a remote ref that is
  98         not an ancestor of the local ref used to overwrite it.
  99         This flag disables the check.  This can cause the
 100         remote repository to lose commits; use it with care.
 101
 102 --repo=<repository>::
 103         This option is only relevant if no <repository> argument is
 104         passed in the invocation. In this case, 'git-push' derives the
 105         remote name from the current branch: If it tracks a remote
 106         branch, then that remote repository is pushed to. Otherwise,
 107         the name "origin" is used. For this latter case, this option
 108         can be used to override the name "origin". In other words,
 109         the difference between these two commands
 110 +
 111 --------------------------
 112 git push public         #1
 113 git push --repo=public  #2
 114 --------------------------
 115 +
 116 is that #1 always pushes to "public" whereas #2 pushes to "public"
 117 only if the current branch does not track a remote branch. This is
 118 useful if you write an alias or script around 'git-push'.
 119
 120 --thin::
 121 --no-thin::
 122         These options are passed to 'git-send-pack'.  Thin
 123         transfer spends extra cycles to minimize the number of
 124         objects to be sent and meant to be used on slower connection.
 125
 126 -v::
 127 --verbose::
 128         Run verbosely.
 129
 130 include::urls-remotes.txt[]
 131
 132 OUTPUT
 133 ------
 134
 135 The output of "git push" depends on the transport method used; this
 136 section describes the output when pushing over the git protocol (either
 137 locally or via ssh).
 138
 139 The status of the push is output in tabular form, with each line
 140 representing the status of a single ref. Each line is of the form:
 141
 142 -------------------------------
 143  <flag> <summary> <from> -> <to> (<reason>)
 144 -------------------------------
 145
 146 flag::
 147         A single character indicating the status of the ref. This is
 148         blank for a successfully pushed ref, `!` for a ref that was
 149         rejected or failed to push, and '=' for a ref that was up to
 150         date and did not need pushing (note that the status of up to
 151         date refs is shown only when `git push` is running verbosely).
 152
 153 summary::
 154         For a successfully pushed ref, the summary shows the old and new
 155         values of the ref in a form suitable for using as an argument to
 156         `git log` (this is `<old>..<new>` in most cases, and
 157         `<old>...<new>` for forced non-fast forward updates). For a
 158         failed update, more details are given for the failure.
 159         The string `rejected` indicates that git did not try to send the
 160         ref at all (typically because it is not a fast forward). The
 161         string `remote rejected` indicates that the remote end refused
 162         the update; this rejection is typically caused by a hook on the
 163         remote side. The string `remote failure` indicates that the
 164         remote end did not report the successful update of the ref
 165         (perhaps because of a temporary error on the remote side, a
 166         break in the network connection, or other transient error).
 167
 168 from::
 169         The name of the local ref being pushed, minus its
 170         `refs/<type>/` prefix. In the case of deletion, the
 171         name of the local ref is omitted.
 172
 173 to::
 174         The name of the remote ref being updated, minus its
 175         `refs/<type>/` prefix.
 176
 177 reason::
 178         A human-readable explanation. In the case of successfully pushed
 179         refs, no explanation is needed. For a failed ref, the reason for
 180         failure is described.
 181
 182 Examples
 183 --------
 184
 185 git push origin master::
 186         Find a ref that matches `master` in the source repository
 187         (most likely, it would find `refs/heads/master`), and update
 188         the same ref (e.g. `refs/heads/master`) in `origin` repository
 189         with it.  If `master` did not exist remotely, it would be
 190         created.
 191
 192 git push origin :experimental::
 193         Find a ref that matches `experimental` in the `origin` repository
 194         (e.g. `refs/heads/experimental`), and delete it.
 195
 196 git push origin master:satellite/master dev:satellite/dev::
 197         Use the source ref that matches `master` (e.g. `refs/heads/master`)
 198         to update the ref that matches `satellite/master` (most probably
 199         `refs/remotes/satellite/master`) in the `origin` repository, then
 200         do the same for `dev` and `satellite/dev`.
 201
 202 git push origin master:refs/heads/experimental::
 203         Create the branch `experimental` in the `origin` repository
 204         by copying the current `master` branch.  This form is only
 205         needed to create a new branch or tag in the remote repository when
 206         the local name and the remote name are different; otherwise,
 207         the ref name on its own will work.
 208
 209 Author
 210 ------
 211 Written by Junio C Hamano <gitster@pobox.com>, later rewritten in C
 212 by Linus Torvalds <torvalds@osdl.org>
 213
 214 Documentation
 215 --------------
 216 Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>.
 217
 218 GIT
 219 ---
 220 Part of the linkgit:git[1] suite