Merge git://git.bogomips.org/git-svn
[git/git.git] / Documentation / git-push.txt
CommitLineData
215a7ad1
JH
1git-push(1)
2===========
7fc9d69f
JH
3
4NAME
5----
7bd7f280 6git-push - Update remote refs along with associated objects
7fc9d69f
JH
7
8
9SYNOPSIS
10--------
97925fde 11[verse]
bed5122f 12'git push' [--all | --mirror | --tags] [--dry-run] [--receive-pack=<git-receive-pack>]
bf07cc58 13 [--repo=<repository>] [-f | --force] [-v | --verbose]
2c9693bd 14 [<repository> <refspec>...]
7fc9d69f
JH
15
16DESCRIPTION
17-----------
ab9b3138
JH
18
19Updates remote refs using local refs, while sending objects
20necessary to complete the given refs.
7fc9d69f 21
cc55aaec 22You can make interesting things happen to a repository
eb0362a4 23every time you push into it, by setting up 'hooks' there. See
5162e697 24documentation for linkgit:git-receive-pack[1].
eb0362a4 25
7fc9d69f 26
d6aba61f
CJ
27OPTIONS[[OPTIONS]]
28------------------
3598a308 29<repository>::
85a97d4e 30 The "remote" repository that is destination of a push
98347fee
AM
31 operation. This parameter can be either a URL
32 (see the section <<URLS,GIT URLS>> below) or the name
33 of a remote (see the section <<REMOTES,REMOTES>> below).
3598a308 34
2c9693bd 35<refspec>...::
7a0d911f
JH
36 The format of a <refspec> parameter is an optional plus
37 `{plus}`, followed by the source ref <src>, followed
38 by a colon `:`, followed by the destination ref <dst>.
39 It is used to specify with what <src> object the <dst> ref
40 in the remote repository is to be updated.
3598a308 41+
80391846
AM
42The <src> is often the name of the branch you would want to push, but
43it can be any arbitrary "SHA-1 expression", such as `master~4` or
44`HEAD` (see linkgit:git-rev-parse[1]).
3598a308 45+
80391846
AM
46The <dst> tells which ref on the remote side is updated with this
47push. Arbitrary expressions cannot be used here, an actual ref must
48be named. If `:`<dst> is omitted, the same ref as <src> will be
49updated.
3598a308 50+
149f6ddf
MB
51The object referenced by <src> is used to update the <dst> reference
52on the remote side, but by default this is only allowed if the
53update can fast forward <dst>. By having the optional leading `{plus}`,
54you can tell git to update the <dst> ref even when the update is not a
55fast forward. This does *not* attempt to merge <src> into <dst>. See
56EXAMPLES below for details.
3598a308 57+
80391846 58`tag <tag>` means the same as `refs/tags/<tag>:refs/tags/<tag>`.
25fb6290
JH
59+
60Pushing an empty <src> allows you to delete the <dst> ref from
61the remote repository.
a83619d6 62+
149f6ddf 63The special refspec `:` (or `{plus}:` to allow non-fast forward updates)
89edd5a9
AM
64directs git to push "matching" branches: for every branch that exists on
65the local side, the remote side is updated if a branch of the same name
a83619d6
PB
66already exists on the remote side. This is the default operation mode
67if no explicit refspec is found (that is neither on the command line
68nor in any Push line of the corresponding remotes file---see below).
7fc9d69f 69
3240240f 70--all::
cc55aaec 71 Instead of naming each ref to push, specifies that all
5c633a4c 72 refs under `$GIT_DIR/refs/heads/` be pushed.
d6a73596 73
3240240f 74--mirror::
ff206748 75 Instead of naming each ref to push, specifies that all
73f03627
SP
76 refs under `$GIT_DIR/refs/` (which includes but is not
77 limited to `refs/heads/`, `refs/remotes/`, and `refs/tags/`)
ff206748
AW
78 be mirrored to the remote repository. Newly created local
79 refs will be pushed to the remote end, locally updated refs
80 will be force updated on the remote end, and deleted refs
84bb2dfd
PB
81 will be removed from the remote end. This is the default
82 if the configuration option `remote.<remote>.mirror` is
83 set.
ff206748 84
3240240f 85--dry-run::
11f2441f
BE
86 Do everything except actually send the updates.
87
3240240f 88--tags::
42301e34
JH
89 All refs under `$GIT_DIR/refs/tags` are pushed, in
90 addition to refspecs explicitly listed on the command
91 line.
92
3240240f 93--receive-pack=<git-receive-pack>::
4fc988ef 94--exec=<git-receive-pack>::
ba020ef5 95 Path to the 'git-receive-pack' program on the remote
5214f770
UKK
96 end. Sometimes useful when pushing to a remote
97 repository over ssh, and you do not have the program in
98 a directory on the default $PATH.
99
3240240f
SB
100-f::
101--force::
f0fff36e 102 Usually, the command refuses to update a remote ref that is
64a476e6 103 not an ancestor of the local ref used to overwrite it.
f0fff36e
BF
104 This flag disables the check. This can cause the
105 remote repository to lose commits; use it with care.
7fc9d69f 106
bf07cc58
JS
107--repo=<repository>::
108 This option is only relevant if no <repository> argument is
109 passed in the invocation. In this case, 'git-push' derives the
110 remote name from the current branch: If it tracks a remote
111 branch, then that remote repository is pushed to. Otherwise,
112 the name "origin" is used. For this latter case, this option
113 can be used to override the name "origin". In other words,
114 the difference between these two commands
115+
116--------------------------
117git push public #1
118git push --repo=public #2
119--------------------------
120+
121is that #1 always pushes to "public" whereas #2 pushes to "public"
122only if the current branch does not track a remote branch. This is
123useful if you write an alias or script around 'git-push'.
dc36f265 124
3240240f
SB
125--thin::
126--no-thin::
ba020ef5 127 These options are passed to 'git-send-pack'. Thin
dc36f265
JH
128 transfer spends extra cycles to minimize the number of
129 objects to be sent and meant to be used on slower connection.
130
3240240f
SB
131-v::
132--verbose::
dc36f265
JH
133 Run verbosely.
134
37ba0561 135include::urls-remotes.txt[]
eb0362a4 136
066a5268
JK
137OUTPUT
138------
139
140The output of "git push" depends on the transport method used; this
141section describes the output when pushing over the git protocol (either
142locally or via ssh).
143
144The status of the push is output in tabular form, with each line
145representing the status of a single ref. Each line is of the form:
146
147-------------------------------
148 <flag> <summary> <from> -> <to> (<reason>)
149-------------------------------
150
151flag::
152 A single character indicating the status of the ref. This is
153 blank for a successfully pushed ref, `!` for a ref that was
154 rejected or failed to push, and '=' for a ref that was up to
155 date and did not need pushing (note that the status of up to
156 date refs is shown only when `git push` is running verbosely).
157
158summary::
159 For a successfully pushed ref, the summary shows the old and new
160 values of the ref in a form suitable for using as an argument to
161 `git log` (this is `<old>..<new>` in most cases, and
162 `<old>...<new>` for forced non-fast forward updates). For a
163 failed update, more details are given for the failure.
164 The string `rejected` indicates that git did not try to send the
165 ref at all (typically because it is not a fast forward). The
166 string `remote rejected` indicates that the remote end refused
167 the update; this rejection is typically caused by a hook on the
168 remote side. The string `remote failure` indicates that the
169 remote end did not report the successful update of the ref
170 (perhaps because of a temporary error on the remote side, a
171 break in the network connection, or other transient error).
172
173from::
174 The name of the local ref being pushed, minus its
175 `refs/<type>/` prefix. In the case of deletion, the
176 name of the local ref is omitted.
177
178to::
179 The name of the remote ref being updated, minus its
180 `refs/<type>/` prefix.
181
182reason::
183 A human-readable explanation. In the case of successfully pushed
184 refs, no explanation is needed. For a failed ref, the reason for
185 failure is described.
bb9fca80
JH
186
187Examples
188--------
189
d6aba61f
CJ
190git push::
191 Works like `git push <remote>`, where <remote> is the
192 current branch's remote (or `origin`, if no remote is
193 configured for the current branch).
194
195git push origin::
196 Without additional configuration, works like
197 `git push origin :`.
198+
199The default behavior of this command when no <refspec> is given can be
200configured by setting the `push` option of the remote.
201+
202For example, to default to pushing only the current branch to `origin`
203use `git config remote.origin.push HEAD`. Any valid <refspec> (like
204the ones in the examples below) can be configured as the default for
205`git push origin`.
206
207git push origin :::
208 Push "matching" branches to `origin`. See
209 <refspec> in the <<OPTIONS,OPTIONS>> section above for a
210 description of "matching" branches.
211
bb9fca80
JH
212git push origin master::
213 Find a ref that matches `master` in the source repository
214 (most likely, it would find `refs/heads/master`), and update
215 the same ref (e.g. `refs/heads/master`) in `origin` repository
491b1b11
SV
216 with it. If `master` did not exist remotely, it would be
217 created.
bb9fca80 218
17507832
AM
219git push origin HEAD::
220 A handy way to push the current branch to the same name on the
221 remote.
bb9fca80 222
2c9693bd
AMS
223git push origin master:satellite/master dev:satellite/dev::
224 Use the source ref that matches `master` (e.g. `refs/heads/master`)
225 to update the ref that matches `satellite/master` (most probably
226 `refs/remotes/satellite/master`) in the `origin` repository, then
227 do the same for `dev` and `satellite/dev`.
bb9fca80 228
17507832
AM
229git push origin HEAD:master::
230 Push the current branch to the remote ref matching `master` in the
231 `origin` repository. This form is convenient to push the current
232 branch without thinking about its local name.
233
4e560158
SP
234git push origin master:refs/heads/experimental::
235 Create the branch `experimental` in the `origin` repository
491b1b11
SV
236 by copying the current `master` branch. This form is only
237 needed to create a new branch or tag in the remote repository when
238 the local name and the remote name are different; otherwise,
239 the ref name on its own will work.
4e560158 240
17507832
AM
241git push origin :experimental::
242 Find a ref that matches `experimental` in the `origin` repository
243 (e.g. `refs/heads/experimental`), and delete it.
244
149f6ddf
MB
245git push origin {plus}dev:master::
246 Update the origin repository's master branch with the dev branch,
247 allowing non-fast forward updates. *This can leave unreferenced
248 commits dangling in the origin repository.* Consider the
249 following situation, where a fast forward is not possible:
250+
251----
252 o---o---o---A---B origin/master
253 \
254 X---Y---Z dev
255----
256+
257The above command would change the origin repository to
258+
259----
260 A---B (unnamed branch)
261 /
262 o---o---o---X---Y---Z master
263----
264+
265Commits A and B would no longer belong to a branch with a symbolic name,
266and so would be unreachable. As such, these commits would be removed by
267a `git gc` command on the origin repository.
268
17507832 269
7fc9d69f
JH
270Author
271------
59eb68aa 272Written by Junio C Hamano <gitster@pobox.com>, later rewritten in C
25fb6290 273by Linus Torvalds <torvalds@osdl.org>
7fc9d69f
JH
274
275Documentation
276--------------
277Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>.
278
279GIT
280---
9e1f0a85 281Part of the linkgit:git[1] suite