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