Git 1.8.2.3
[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]
9f67fee2 12'git push' [--all | --mirror | --tags] [-n | --dry-run] [--receive-pack=<git-receive-pack>]
6ddba5e2 13 [--repo=<repository>] [-f | --force] [--prune] [-v | --verbose] [-u | --set-upstream]
e3163c75 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
cfe1348d
JH
26When the command line does not specify where to push with the
27`<repository>` argument, `branch.*.remote` configuration for the
28current branch is consulted to determine where to push. If the
29configuration is missing, it defaults to 'origin'.
30
31When the command line does not specify what to push with `<refspec>...`
32arguments or `--all`, `--mirror`, `--tags` options, the command finds
33the default `<refspec>` by consulting `remote.*.push` configuration,
34and if it is not found, honors `push.default` configuration to decide
35what to push (See gitlink:git-config[1] for the meaning of `push.default`).
36
7fc9d69f 37
d6aba61f
CJ
38OPTIONS[[OPTIONS]]
39------------------
3598a308 40<repository>::
85a97d4e 41 The "remote" repository that is destination of a push
98347fee
AM
42 operation. This parameter can be either a URL
43 (see the section <<URLS,GIT URLS>> below) or the name
44 of a remote (see the section <<REMOTES,REMOTES>> below).
3598a308 45
2c9693bd 46<refspec>...::
cfe1348d 47 Specify what destination ref to update with what source object.
7a0d911f 48 The format of a <refspec> parameter is an optional plus
cfe1348d 49 `+`, followed by the source object <src>, followed
7a0d911f 50 by a colon `:`, followed by the destination ref <dst>.
3598a308 51+
80391846
AM
52The <src> is often the name of the branch you would want to push, but
53it can be any arbitrary "SHA-1 expression", such as `master~4` or
9d83e382 54`HEAD` (see linkgit:gitrevisions[7]).
3598a308 55+
80391846
AM
56The <dst> tells which ref on the remote side is updated with this
57push. Arbitrary expressions cannot be used here, an actual ref must
58be named. If `:`<dst> is omitted, the same ref as <src> will be
59updated.
3598a308 60+
149f6ddf 61The object referenced by <src> is used to update the <dst> reference
dbfeddb1 62on the remote side. By default this is only allowed if <dst> is not
40eff179 63a tag (annotated or lightweight), and then only if it can fast-forward
2de9b711 64<dst>. By having the optional leading `+`, you can tell Git to update
40eff179
CR
65the <dst> ref even if it is not allowed by default (e.g., it is not a
66fast-forward.) This does *not* attempt to merge <src> into <dst>. See
149f6ddf 67EXAMPLES below for details.
3598a308 68+
80391846 69`tag <tag>` means the same as `refs/tags/<tag>:refs/tags/<tag>`.
25fb6290
JH
70+
71Pushing an empty <src> allows you to delete the <dst> ref from
72the remote repository.
a83619d6 73+
6cf378f0 74The special refspec `:` (or `+:` to allow non-fast-forward updates)
2de9b711 75directs Git to push "matching" branches: for every branch that exists on
89edd5a9 76the local side, the remote side is updated if a branch of the same name
cfe1348d 77already exists on the remote side.
7fc9d69f 78
3240240f 79--all::
cc55aaec 80 Instead of naming each ref to push, specifies that all
cc1b8d8b 81 refs under `refs/heads/` be pushed.
d6a73596 82
6ddba5e2
FC
83--prune::
84 Remove remote branches that don't have a local counterpart. For example
85 a remote branch `tmp` will be removed if a local branch with the same
86 name doesn't exist any more. This also respects refspecs, e.g.
6cf378f0 87 `git push --prune remote refs/heads/*:refs/tmp/*` would
6ddba5e2
FC
88 make sure that remote `refs/tmp/foo` will be removed if `refs/heads/foo`
89 doesn't exist.
90
3240240f 91--mirror::
ff206748 92 Instead of naming each ref to push, specifies that all
cc1b8d8b 93 refs under `refs/` (which includes but is not
73f03627 94 limited to `refs/heads/`, `refs/remotes/`, and `refs/tags/`)
ff206748
AW
95 be mirrored to the remote repository. Newly created local
96 refs will be pushed to the remote end, locally updated refs
97 will be force updated on the remote end, and deleted refs
84bb2dfd
PB
98 will be removed from the remote end. This is the default
99 if the configuration option `remote.<remote>.mirror` is
100 set.
ff206748 101
9f67fee2 102-n::
3240240f 103--dry-run::
11f2441f
BE
104 Do everything except actually send the updates.
105
1965ff74
LA
106--porcelain::
107 Produce machine-readable output. The output status line for each ref
108 will be tab-separated and sent to stdout instead of stderr. The full
109 symbolic names of the refs will be given.
110
f517f1f2
JK
111--delete::
112 All listed refs are deleted from the remote repository. This is
113 the same as prefixing all refs with a colon.
114
3240240f 115--tags::
cc1b8d8b 116 All refs under `refs/tags` are pushed, in
42301e34
JH
117 addition to refspecs explicitly listed on the command
118 line.
119
3240240f 120--receive-pack=<git-receive-pack>::
4fc988ef 121--exec=<git-receive-pack>::
ba020ef5 122 Path to the 'git-receive-pack' program on the remote
5214f770
UKK
123 end. Sometimes useful when pushing to a remote
124 repository over ssh, and you do not have the program in
125 a directory on the default $PATH.
126
3240240f
SB
127-f::
128--force::
f0fff36e 129 Usually, the command refuses to update a remote ref that is
64a476e6 130 not an ancestor of the local ref used to overwrite it.
f0fff36e
BF
131 This flag disables the check. This can cause the
132 remote repository to lose commits; use it with care.
7fc9d69f 133
bf07cc58
JS
134--repo=<repository>::
135 This option is only relevant if no <repository> argument is
0b444cdb 136 passed in the invocation. In this case, 'git push' derives the
bf07cc58
JS
137 remote name from the current branch: If it tracks a remote
138 branch, then that remote repository is pushed to. Otherwise,
139 the name "origin" is used. For this latter case, this option
140 can be used to override the name "origin". In other words,
141 the difference between these two commands
142+
143--------------------------
144git push public #1
145git push --repo=public #2
146--------------------------
147+
148is that #1 always pushes to "public" whereas #2 pushes to "public"
149only if the current branch does not track a remote branch. This is
0b444cdb 150useful if you write an alias or script around 'git push'.
dc36f265 151
0ed3a111
TR
152-u::
153--set-upstream::
154 For every branch that is up to date or successfully pushed, add
155 upstream (tracking) reference, used by argument-less
156 linkgit:git-pull[1] and other commands. For more information,
157 see 'branch.<name>.merge' in linkgit:git-config[1].
158
3240240f
SB
159--thin::
160--no-thin::
738820a9
SB
161 These options are passed to linkgit:git-send-pack[1]. A thin transfer
162 significantly reduces the amount of sent data when the sender and
163 receiver share many of the same objects in common. The default is
164 \--thin.
dc36f265 165
989119d9
JK
166-q::
167--quiet::
168 Suppress all output, including the listing of updated refs,
78381069
TRC
169 unless an error occurs. Progress is not reported to the standard
170 error stream.
989119d9 171
3240240f
SB
172-v::
173--verbose::
dc36f265
JH
174 Run verbosely.
175
78381069
TRC
176--progress::
177 Progress status is reported on the standard error stream
178 by default when it is attached to a terminal, unless -q
179 is specified. This flag forces progress status even if the
180 standard error stream is not directed to a terminal.
989119d9 181
eb21c732
HV
182--recurse-submodules=check|on-demand::
183 Make sure all submodule commits used by the revisions to be
a6d3bde5 184 pushed are available on a remote-tracking branch. If 'check' is
2de9b711 185 used Git will verify that all submodule commits that changed in
eb21c732
HV
186 the revisions to be pushed are available on at least one remote
187 of the submodule. If any commits are missing the push will be
188 aborted and exit with non-zero status. If 'on-demand' is used
189 all submodules that changed in the revisions to be pushed will
190 be pushed. If on-demand was not able to push all necessary
191 revisions it will also be aborted and exit with non-zero status.
d2b17b32
FG
192
193
37ba0561 194include::urls-remotes.txt[]
eb0362a4 195
066a5268
JK
196OUTPUT
197------
198
199The output of "git push" depends on the transport method used; this
2de9b711 200section describes the output when pushing over the Git protocol (either
066a5268
JK
201locally or via ssh).
202
203The status of the push is output in tabular form, with each line
204representing the status of a single ref. Each line is of the form:
205
206-------------------------------
207 <flag> <summary> <from> -> <to> (<reason>)
208-------------------------------
209
1965ff74
LA
210If --porcelain is used, then each line of the output is of the form:
211
212-------------------------------
213 <flag> \t <from>:<to> \t <summary> (<reason>)
214-------------------------------
215
b7047abc
JH
216The status of up-to-date refs is shown only if --porcelain or --verbose
217option is used.
218
066a5268 219flag::
b7047abc
JH
220 A single character indicating the status of the ref:
221(space);; for a successfully pushed fast-forward;
6cf378f0 222`+`;; for a successful forced update;
b7047abc
JH
223`-`;; for a successfully deleted ref;
224`*`;; for a successfully pushed new ref;
225`!`;; for a ref that was rejected or failed to push; and
226`=`;; for a ref that was up to date and did not need pushing.
066a5268
JK
227
228summary::
229 For a successfully pushed ref, the summary shows the old and new
230 values of the ref in a form suitable for using as an argument to
231 `git log` (this is `<old>..<new>` in most cases, and
6cf378f0 232 `<old>...<new>` for forced non-fast-forward updates).
9a9fb5d3
TR
233+
234For a failed update, more details are given:
235+
236--
237rejected::
238 Git did not try to send the ref at all, typically because it
239 is not a fast-forward and you did not force the update.
240
241remote rejected::
242 The remote end refused the update. Usually caused by a hook
243 on the remote side, or because the remote repository has one
244 of the following safety options in effect:
245 `receive.denyCurrentBranch` (for pushes to the checked out
246 branch), `receive.denyNonFastForwards` (for forced
247 non-fast-forward updates), `receive.denyDeletes` or
248 `receive.denyDeleteCurrent`. See linkgit:git-config[1].
249
250remote failure::
251 The remote end did not report the successful update of the ref,
252 perhaps because of a temporary error on the remote side, a
253 break in the network connection, or other transient error.
254--
066a5268
JK
255
256from::
257 The name of the local ref being pushed, minus its
258 `refs/<type>/` prefix. In the case of deletion, the
259 name of the local ref is omitted.
260
261to::
262 The name of the remote ref being updated, minus its
263 `refs/<type>/` prefix.
264
265reason::
266 A human-readable explanation. In the case of successfully pushed
267 refs, no explanation is needed. For a failed ref, the reason for
268 failure is described.
bb9fca80 269
07436e43
MM
270Note about fast-forwards
271------------------------
272
273When an update changes a branch (or more in general, a ref) that used to
274point at commit A to point at another commit B, it is called a
275fast-forward update if and only if B is a descendant of A.
276
277In a fast-forward update from A to B, the set of commits that the original
278commit A built on top of is a subset of the commits the new commit B
279builds on top of. Hence, it does not lose any history.
280
281In contrast, a non-fast-forward update will lose history. For example,
282suppose you and somebody else started at the same commit X, and you built
283a history leading to commit B while the other person built a history
284leading to commit A. The history looks like this:
285
286----------------
287
288 B
289 /
290 ---X---A
291
292----------------
293
294Further suppose that the other person already pushed changes leading to A
6b6e063c
MS
295back to the original repository from which you two obtained the original
296commit X.
07436e43
MM
297
298The push done by the other person updated the branch that used to point at
299commit X to point at commit A. It is a fast-forward.
300
301But if you try to push, you will attempt to update the branch (that
302now points at A) with commit B. This does _not_ fast-forward. If you did
303so, the changes introduced by commit A will be lost, because everybody
304will now start building on top of B.
305
306The command by default does not allow an update that is not a fast-forward
307to prevent such loss of history.
308
309If you do not want to lose your work (history from X to B) nor the work by
310the other person (history from X to A), you would need to first fetch the
311history from the repository, create a history that contains changes done
312by both parties, and push the result back.
313
314You can perform "git pull", resolve potential conflicts, and "git push"
315the result. A "git pull" will create a merge commit C between commits A
316and B.
317
318----------------
319
320 B---C
321 / /
322 ---X---A
323
324----------------
325
326Updating A with the resulting merge commit will fast-forward and your
327push will be accepted.
328
329Alternatively, you can rebase your change between X and B on top of A,
330with "git pull --rebase", and push the result back. The rebase will
331create a new commit D that builds the change between X and B on top of
332A.
333
334----------------
335
336 B D
337 / /
338 ---X---A
339
340----------------
341
342Again, updating A with this commit will fast-forward and your push will be
343accepted.
344
345There is another common situation where you may encounter non-fast-forward
346rejection when you try to push, and it is possible even when you are
347pushing into a repository nobody else pushes into. After you push commit
348A yourself (in the first picture in this section), replace it with "git
349commit --amend" to produce commit B, and you try to push it out, because
350forgot that you have pushed A out already. In such a case, and only if
351you are certain that nobody in the meantime fetched your earlier commit A
352(and started building on top of it), you can run "git push --force" to
353overwrite it. In other words, "git push --force" is a method reserved for
354a case where you do mean to lose history.
355
356
bb9fca80
JH
357Examples
358--------
359
5d2fc913 360`git push`::
d6aba61f
CJ
361 Works like `git push <remote>`, where <remote> is the
362 current branch's remote (or `origin`, if no remote is
363 configured for the current branch).
364
5d2fc913 365`git push origin`::
d6aba61f
CJ
366 Without additional configuration, works like
367 `git push origin :`.
368+
369The default behavior of this command when no <refspec> is given can be
1ec6f488
RR
370configured by setting the `push` option of the remote, or the `push.default`
371configuration variable.
d6aba61f
CJ
372+
373For example, to default to pushing only the current branch to `origin`
374use `git config remote.origin.push HEAD`. Any valid <refspec> (like
375the ones in the examples below) can be configured as the default for
376`git push origin`.
377
5d2fc913 378`git push origin :`::
d6aba61f
CJ
379 Push "matching" branches to `origin`. See
380 <refspec> in the <<OPTIONS,OPTIONS>> section above for a
381 description of "matching" branches.
382
5d2fc913 383`git push origin master`::
bb9fca80
JH
384 Find a ref that matches `master` in the source repository
385 (most likely, it would find `refs/heads/master`), and update
386 the same ref (e.g. `refs/heads/master`) in `origin` repository
491b1b11
SV
387 with it. If `master` did not exist remotely, it would be
388 created.
bb9fca80 389
5d2fc913 390`git push origin HEAD`::
17507832
AM
391 A handy way to push the current branch to the same name on the
392 remote.
bb9fca80 393
b48990e7 394`git push mothership master:satellite/master dev:satellite/dev`::
2c9693bd
AMS
395 Use the source ref that matches `master` (e.g. `refs/heads/master`)
396 to update the ref that matches `satellite/master` (most probably
b48990e7 397 `refs/remotes/satellite/master`) in the `mothership` repository;
2c9693bd 398 do the same for `dev` and `satellite/dev`.
b48990e7
JH
399+
400This is to emulate `git fetch` run on the `mothership` using `git
401push` that is run in the opposite direction in order to integrate
402the work done on `satellite`, and is often necessary when you can
403only make connection in one way (i.e. satellite can ssh into
404mothership but mothership cannot initiate connection to satellite
405because the latter is behind a firewall or does not run sshd).
406+
407After running this `git push` on the `satellite` machine, you would
408ssh into the `mothership` and run `git merge` there to complete the
409emulation of `git pull` that were run on `mothership` to pull changes
410made on `satellite`.
bb9fca80 411
5d2fc913 412`git push origin HEAD:master`::
17507832
AM
413 Push the current branch to the remote ref matching `master` in the
414 `origin` repository. This form is convenient to push the current
415 branch without thinking about its local name.
416
5d2fc913 417`git push origin master:refs/heads/experimental`::
4e560158 418 Create the branch `experimental` in the `origin` repository
491b1b11
SV
419 by copying the current `master` branch. This form is only
420 needed to create a new branch or tag in the remote repository when
421 the local name and the remote name are different; otherwise,
422 the ref name on its own will work.
4e560158 423
5d2fc913 424`git push origin :experimental`::
17507832
AM
425 Find a ref that matches `experimental` in the `origin` repository
426 (e.g. `refs/heads/experimental`), and delete it.
427
6cf378f0 428`git push origin +dev:master`::
149f6ddf 429 Update the origin repository's master branch with the dev branch,
a75d7b54 430 allowing non-fast-forward updates. *This can leave unreferenced
149f6ddf 431 commits dangling in the origin repository.* Consider the
a75d7b54 432 following situation, where a fast-forward is not possible:
149f6ddf
MB
433+
434----
435 o---o---o---A---B origin/master
436 \
437 X---Y---Z dev
438----
439+
440The above command would change the origin repository to
441+
442----
443 A---B (unnamed branch)
444 /
445 o---o---o---X---Y---Z master
446----
447+
448Commits A and B would no longer belong to a branch with a symbolic name,
449and so would be unreachable. As such, these commits would be removed by
450a `git gc` command on the origin repository.
451
7fc9d69f
JH
452GIT
453---
9e1f0a85 454Part of the linkgit:git[1] suite