]>
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] |
425b4d7f | 12 | 'git push' [--all | --branches | --mirror | --tags] [--follow-tags] [--atomic] [-n | --dry-run] [--receive-pack=<git-receive-pack>] |
f6d83e21 | 13 | [--repo=<repository>] [-f | --force] [-d | --delete] [--prune] [-q | --quiet] [-v | --verbose] |
97c5d246 | 14 | [-u | --set-upstream] [-o <string> | --push-option=<string>] |
a81383ba | 15 | [--[no-]signed|--signed=(true|false|if-asked)] |
3b5bf965 | 16 | [--force-with-lease[=<refname>[:<expect>]] [--force-if-includes]] |
90d32d1f | 17 | [--no-verify] [<repository> [<refspec>...]] |
7fc9d69f JH |
18 | |
19 | DESCRIPTION | |
20 | ----------- | |
ab9b3138 JH |
21 | |
22 | Updates remote refs using local refs, while sending objects | |
23 | necessary to complete the given refs. | |
7fc9d69f | 24 | |
cc55aaec | 25 | You can make interesting things happen to a repository |
eb0362a4 | 26 | every time you push into it, by setting up 'hooks' there. See |
5162e697 | 27 | documentation for linkgit:git-receive-pack[1]. |
eb0362a4 | 28 | |
cfe1348d JH |
29 | When the command line does not specify where to push with the |
30 | `<repository>` argument, `branch.*.remote` configuration for the | |
31 | current branch is consulted to determine where to push. If the | |
32 | configuration is missing, it defaults to 'origin'. | |
33 | ||
34 | When the command line does not specify what to push with `<refspec>...` | |
35 | arguments or `--all`, `--mirror`, `--tags` options, the command finds | |
36 | the default `<refspec>` by consulting `remote.*.push` configuration, | |
37 | and if it is not found, honors `push.default` configuration to decide | |
366c8d4c | 38 | what to push (See linkgit:git-config[1] for the meaning of `push.default`). |
cfe1348d | 39 | |
fd3ba590 | 40 | When neither the command-line nor the configuration specifies what to |
f6b1fb37 MM |
41 | push, the default behavior is used, which corresponds to the `simple` |
42 | value for `push.default`: the current branch is pushed to the | |
43 | corresponding upstream branch, but as a safety measure, the push is | |
44 | aborted if the upstream branch does not have the same name as the | |
45 | local one. | |
46 | ||
7fc9d69f | 47 | |
d6aba61f CJ |
48 | OPTIONS[[OPTIONS]] |
49 | ------------------ | |
3598a308 | 50 | <repository>:: |
0a4f051f | 51 | The "remote" repository that is the destination of a push |
98347fee AM |
52 | operation. This parameter can be either a URL |
53 | (see the section <<URLS,GIT URLS>> below) or the name | |
54 | of a remote (see the section <<REMOTES,REMOTES>> below). | |
3598a308 | 55 | |
2c9693bd | 56 | <refspec>...:: |
cfe1348d | 57 | Specify what destination ref to update with what source object. |
7a0d911f | 58 | The format of a <refspec> parameter is an optional plus |
cfe1348d | 59 | `+`, followed by the source object <src>, followed |
7a0d911f | 60 | by a colon `:`, followed by the destination ref <dst>. |
3598a308 | 61 | + |
80391846 AM |
62 | The <src> is often the name of the branch you would want to push, but |
63 | it can be any arbitrary "SHA-1 expression", such as `master~4` or | |
9d83e382 | 64 | `HEAD` (see linkgit:gitrevisions[7]). |
3598a308 | 65 | + |
80391846 AM |
66 | The <dst> tells which ref on the remote side is updated with this |
67 | push. Arbitrary expressions cannot be used here, an actual ref must | |
ca02465b JH |
68 | be named. |
69 | If `git push [<repository>]` without any `<refspec>` argument is set to | |
70 | update some ref at the destination with `<src>` with | |
71 | `remote.<repository>.push` configuration variable, `:<dst>` part can | |
3b19dba7 | 72 | be omitted--such a push will update a ref that `<src>` normally updates |
ca02465b JH |
73 | without any `<refspec>` on the command line. Otherwise, missing |
74 | `:<dst>` means to update the same ref as the `<src>`. | |
3598a308 | 75 | + |
2219c09e ÆAB |
76 | If <dst> doesn't start with `refs/` (e.g. `refs/heads/master`) we will |
77 | try to infer where in `refs/*` on the destination <repository> it | |
24966cd9 | 78 | belongs based on the type of <src> being pushed and whether <dst> |
2219c09e ÆAB |
79 | is ambiguous. |
80 | + | |
81 | -- | |
82 | * If <dst> unambiguously refers to a ref on the <repository> remote, | |
83 | then push to that ref. | |
84 | ||
85 | * If <src> resolves to a ref starting with refs/heads/ or refs/tags/, | |
86 | then prepend that to <dst>. | |
87 | ||
88 | * Other ambiguity resolutions might be added in the future, but for | |
89 | now any other cases will error out with an error indicating what we | |
90 | tried, and depending on the `advice.pushUnqualifiedRefname` | |
91 | configuration (see linkgit:git-config[1]) suggest what refs/ | |
92 | namespace you may have wanted to push to. | |
93 | ||
94 | -- | |
95 | + | |
149f6ddf | 96 | The object referenced by <src> is used to update the <dst> reference |
fe802bd2 ÆAB |
97 | on the remote side. Whether this is allowed depends on where in |
98 | `refs/*` the <dst> reference lives as described in detail below, in | |
99 | those sections "update" means any modifications except deletes, which | |
100 | as noted after the next few sections are treated differently. | |
3598a308 | 101 | + |
fe802bd2 ÆAB |
102 | The `refs/heads/*` namespace will only accept commit objects, and |
103 | updates only if they can be fast-forwarded. | |
104 | + | |
105 | The `refs/tags/*` namespace will accept any kind of object (as | |
106 | commits, trees and blobs can be tagged), and any updates to them will | |
107 | be rejected. | |
108 | + | |
109 | It's possible to push any type of object to any namespace outside of | |
110 | `refs/{tags,heads}/*`. In the case of tags and commits, these will be | |
111 | treated as if they were the commits inside `refs/heads/*` for the | |
112 | purposes of whether the update is allowed. | |
113 | + | |
114 | I.e. a fast-forward of commits and tags outside `refs/{tags,heads}/*` | |
115 | is allowed, even in cases where what's being fast-forwarded is not a | |
116 | commit, but a tag object which happens to point to a new commit which | |
117 | is a fast-forward of the commit the last tag (or commit) it's | |
118 | replacing. Replacing a tag with an entirely different tag is also | |
119 | allowed, if it points to the same commit, as well as pushing a peeled | |
120 | tag, i.e. pushing the commit that existing tag object points to, or a | |
121 | new tag object which an existing commit points to. | |
122 | + | |
123 | Tree and blob objects outside of `refs/{tags,heads}/*` will be treated | |
124 | the same way as if they were inside `refs/tags/*`, any update of them | |
125 | will be rejected. | |
126 | + | |
127 | All of the rules described above about what's not allowed as an update | |
128 | can be overridden by adding an the optional leading `+` to a refspec | |
129 | (or using `--force` command line option). The only exception to this | |
130 | is that no amount of forcing will make the `refs/heads/*` namespace | |
131 | accept a non-commit object. Hooks and configuration can also override | |
132 | or amend these rules, see e.g. `receive.denyNonFastForwards` in | |
f4ec16ad | 133 | linkgit:git-config[1] and `pre-receive` and `update` in |
fe802bd2 ÆAB |
134 | linkgit:githooks[5]. |
135 | + | |
136 | Pushing an empty <src> allows you to delete the <dst> ref from the | |
137 | remote repository. Deletions are always accepted without a leading `+` | |
138 | in the refspec (or `--force`), except when forbidden by configuration | |
139 | or hooks. See `receive.denyDeletes` in linkgit:git-config[1] and | |
140 | `pre-receive` and `update` in linkgit:githooks[5]. | |
a83619d6 | 141 | + |
6cf378f0 | 142 | The special refspec `:` (or `+:` to allow non-fast-forward updates) |
2de9b711 | 143 | directs Git to push "matching" branches: for every branch that exists on |
89edd5a9 | 144 | the local side, the remote side is updated if a branch of the same name |
cfe1348d | 145 | already exists on the remote side. |
8da6128c ÆAB |
146 | + |
147 | `tag <tag>` means the same as `refs/tags/<tag>:refs/tags/<tag>`. | |
7fc9d69f | 148 | |
3240240f | 149 | --all:: |
425b4d7f | 150 | --branches:: |
b2ed944a JH |
151 | Push all branches (i.e. refs under `refs/heads/`); cannot be |
152 | used with other <refspec>. | |
d6a73596 | 153 | |
6ddba5e2 FC |
154 | --prune:: |
155 | Remove remote branches that don't have a local counterpart. For example | |
156 | a remote branch `tmp` will be removed if a local branch with the same | |
157 | name doesn't exist any more. This also respects refspecs, e.g. | |
6cf378f0 | 158 | `git push --prune remote refs/heads/*:refs/tmp/*` would |
6ddba5e2 FC |
159 | make sure that remote `refs/tmp/foo` will be removed if `refs/heads/foo` |
160 | doesn't exist. | |
161 | ||
3240240f | 162 | --mirror:: |
ff206748 | 163 | Instead of naming each ref to push, specifies that all |
cc1b8d8b | 164 | refs under `refs/` (which includes but is not |
73f03627 | 165 | limited to `refs/heads/`, `refs/remotes/`, and `refs/tags/`) |
ff206748 AW |
166 | be mirrored to the remote repository. Newly created local |
167 | refs will be pushed to the remote end, locally updated refs | |
168 | will be force updated on the remote end, and deleted refs | |
84bb2dfd PB |
169 | will be removed from the remote end. This is the default |
170 | if the configuration option `remote.<remote>.mirror` is | |
171 | set. | |
ff206748 | 172 | |
9f67fee2 | 173 | -n:: |
3240240f | 174 | --dry-run:: |
11f2441f BE |
175 | Do everything except actually send the updates. |
176 | ||
1965ff74 LA |
177 | --porcelain:: |
178 | Produce machine-readable output. The output status line for each ref | |
179 | will be tab-separated and sent to stdout instead of stderr. The full | |
180 | symbolic names of the refs will be given. | |
181 | ||
97c5d246 | 182 | -d:: |
f517f1f2 JK |
183 | --delete:: |
184 | All listed refs are deleted from the remote repository. This is | |
185 | the same as prefixing all refs with a colon. | |
186 | ||
3240240f | 187 | --tags:: |
cc1b8d8b | 188 | All refs under `refs/tags` are pushed, in |
42301e34 JH |
189 | addition to refspecs explicitly listed on the command |
190 | line. | |
191 | ||
c2aba155 JH |
192 | --follow-tags:: |
193 | Push all the refs that would be pushed without this option, | |
194 | and also push annotated tags in `refs/tags` that are missing | |
a8a5406a | 195 | from the remote but are pointing at commit-ish that are |
a8bc269f | 196 | reachable from the refs being pushed. This can also be specified |
ae9f6311 TR |
197 | with configuration variable `push.followTags`. For more |
198 | information, see `push.followTags` in linkgit:git-config[1]. | |
a8bc269f | 199 | |
30261094 | 200 | --[no-]signed:: |
a81383ba | 201 | --signed=(true|false|if-asked):: |
a85b377d JH |
202 | GPG-sign the push request to update refs on the receiving |
203 | side, to allow it to be checked by the hooks and/or be | |
30261094 DB |
204 | logged. If `false` or `--no-signed`, no signing will be |
205 | attempted. If `true` or `--signed`, the push will fail if the | |
206 | server does not support signed pushes. If set to `if-asked`, | |
207 | sign if and only if the server supports signed pushes. The push | |
208 | will also fail if the actual call to `gpg --sign` fails. See | |
209 | linkgit:git-receive-pack[1] for the details on the receiving end. | |
a85b377d | 210 | |
d0e8e09c RS |
211 | --[no-]atomic:: |
212 | Use an atomic transaction on the remote side if available. | |
213 | Either all refs are updated, or on error, no refs are updated. | |
214 | If the server does not support atomic pushes the push will fail. | |
215 | ||
d8052750 MP |
216 | -o <option>:: |
217 | --push-option=<option>:: | |
f6a4e61f SB |
218 | Transmit the given string to the server, which passes them to |
219 | the pre-receive as well as the post-receive hook. The given string | |
220 | must not contain a NUL or LF character. | |
d8052750 MP |
221 | When multiple `--push-option=<option>` are given, they are |
222 | all sent to the other side in the order listed on the | |
223 | command line. | |
224 | When no `--push-option=<option>` is given from the command | |
225 | line, the values of configuration variable `push.pushOption` | |
226 | are used instead. | |
f6a4e61f | 227 | |
3240240f | 228 | --receive-pack=<git-receive-pack>:: |
4fc988ef | 229 | --exec=<git-receive-pack>:: |
ba020ef5 | 230 | Path to the 'git-receive-pack' program on the remote |
5214f770 UKK |
231 | end. Sometimes useful when pushing to a remote |
232 | repository over ssh, and you do not have the program in | |
233 | a directory on the default $PATH. | |
234 | ||
28f5d176 JH |
235 | --[no-]force-with-lease:: |
236 | --force-with-lease=<refname>:: | |
237 | --force-with-lease=<refname>:<expect>:: | |
238 | Usually, "git push" refuses to update a remote ref that is | |
239 | not an ancestor of the local ref used to overwrite it. | |
240 | + | |
fddfaf8a PH |
241 | This option overrides this restriction if the current value of the |
242 | remote ref is the expected value. "git push" fails otherwise. | |
28f5d176 JH |
243 | + |
244 | Imagine that you have to rebase what you have already published. | |
245 | You will have to bypass the "must fast-forward" rule in order to | |
246 | replace the history you originally published with the rebased history. | |
247 | If somebody else built on top of your original history while you are | |
69b3367f FC |
248 | rebasing, the tip of the branch at the remote may advance with their |
249 | commit, and blindly pushing with `--force` will lose their work. | |
28f5d176 JH |
250 | + |
251 | This option allows you to say that you expect the history you are | |
252 | updating is what you rebased and want to replace. If the remote ref | |
253 | still points at the commit you specified, you can be sure that no | |
fddfaf8a PH |
254 | other people did anything to the ref. It is like taking a "lease" on |
255 | the ref without explicitly locking it, and the remote ref is updated | |
256 | only if the "lease" is still valid. | |
28f5d176 JH |
257 | + |
258 | `--force-with-lease` alone, without specifying the details, will protect | |
259 | all remote refs that are going to be updated by requiring their | |
260 | current value to be the same as the remote-tracking branch we have | |
fddfaf8a | 261 | for them. |
28f5d176 JH |
262 | + |
263 | `--force-with-lease=<refname>`, without specifying the expected value, will | |
264 | protect the named ref (alone), if it is going to be updated, by | |
265 | requiring its current value to be the same as the remote-tracking | |
266 | branch we have for it. | |
267 | + | |
268 | `--force-with-lease=<refname>:<expect>` will protect the named ref (alone), | |
269 | if it is going to be updated, by requiring its current value to be | |
d132b32b | 270 | the same as the specified value `<expect>` (which is allowed to be |
28f5d176 JH |
271 | different from the remote-tracking branch we have for the refname, |
272 | or we do not even have to have such a remote-tracking branch when | |
eee98e74 JK |
273 | this form is used). If `<expect>` is the empty string, then the named ref |
274 | must not already exist. | |
28f5d176 JH |
275 | + |
276 | Note that all forms other than `--force-with-lease=<refname>:<expect>` | |
277 | that specifies the expected current value of the ref explicitly are | |
278 | still experimental and their semantics may change as we gain experience | |
279 | with this feature. | |
280 | + | |
281 | "--no-force-with-lease" will cancel all the previous --force-with-lease on the | |
282 | command line. | |
f17d642d ÆAB |
283 | + |
284 | A general note on safety: supplying this option without an expected | |
285 | value, i.e. as `--force-with-lease` or `--force-with-lease=<refname>` | |
286 | interacts very badly with anything that implicitly runs `git fetch` on | |
287 | the remote to be pushed to in the background, e.g. `git fetch origin` | |
288 | on your repository in a cronjob. | |
289 | + | |
290 | The protection it offers over `--force` is ensuring that subsequent | |
291 | changes your work wasn't based on aren't clobbered, but this is | |
292 | trivially defeated if some background process is updating refs in the | |
293 | background. We don't have anything except the remote tracking info to | |
294 | go by as a heuristic for refs you're expected to have seen & are | |
295 | willing to clobber. | |
296 | + | |
297 | If your editor or some other system is running `git fetch` in the | |
298 | background for you a way to mitigate this is to simply set up another | |
299 | remote: | |
300 | + | |
301 | git remote add origin-push $(git config remote.origin.url) | |
302 | git fetch origin-push | |
303 | + | |
304 | Now when the background process runs `git fetch origin` the references | |
305 | on `origin-push` won't be updated, and thus commands like: | |
306 | + | |
307 | git push --force-with-lease origin-push | |
308 | + | |
309 | Will fail unless you manually run `git fetch origin-push`. This method | |
310 | is of course entirely defeated by something that runs `git fetch | |
311 | --all`, in that case you'd need to either disable it or do something | |
312 | more tedious like: | |
313 | + | |
314 | git fetch # update 'master' from remote | |
315 | git tag base master # mark our base point | |
316 | git rebase -i master # rewrite some commits | |
317 | git push --force-with-lease=master:base master:master | |
318 | + | |
319 | I.e. create a `base` tag for versions of the upstream code that you've | |
320 | seen and are willing to overwrite, then rewrite history, and finally | |
321 | force push changes to `master` if the remote version is still at | |
322 | `base`, regardless of what your local `remotes/origin/master` has been | |
323 | updated to in the background. | |
3b5bf965 SK |
324 | + |
325 | Alternatively, specifying `--force-if-includes` as an ancillary option | |
326 | along with `--force-with-lease[=<refname>]` (i.e., without saying what | |
327 | exact commit the ref on the remote side must be pointing at, or which | |
328 | refs on the remote side are being protected) at the time of "push" will | |
329 | verify if updates from the remote-tracking refs that may have been | |
330 | implicitly updated in the background are integrated locally before | |
331 | allowing a forced update. | |
28f5d176 | 332 | |
3240240f SB |
333 | -f:: |
334 | --force:: | |
f0fff36e | 335 | Usually, the command refuses to update a remote ref that is |
64a476e6 | 336 | not an ancestor of the local ref used to overwrite it. |
28f5d176 JH |
337 | Also, when `--force-with-lease` option is used, the command refuses |
338 | to update a remote ref whose current value does not match | |
339 | what is expected. | |
340 | + | |
341 | This flag disables these checks, and can cause the remote repository | |
342 | to lose commits; use it with care. | |
343 | + | |
344 | Note that `--force` applies to all the refs that are pushed, hence | |
345 | using it with `push.default` set to `matching` or with multiple push | |
346 | destinations configured with `remote.*.push` may overwrite refs | |
347 | other than the current branch (including local refs that are | |
348 | strictly behind their remote counterpart). To force a push to only | |
349 | one branch, use a `+` in front of the refspec to push (e.g `git push | |
350 | origin +master` to force a push to the `master` branch). See the | |
351 | `<refspec>...` section above for details. | |
7fc9d69f | 352 | |
3b5bf965 SK |
353 | --[no-]force-if-includes:: |
354 | Force an update only if the tip of the remote-tracking ref | |
355 | has been integrated locally. | |
356 | + | |
357 | This option enables a check that verifies if the tip of the | |
358 | remote-tracking ref is reachable from one of the "reflog" entries of | |
359 | the local branch based in it for a rewrite. The check ensures that any | |
360 | updates from the remote have been incorporated locally by rejecting the | |
361 | forced update if that is not the case. | |
362 | + | |
363 | If the option is passed without specifying `--force-with-lease`, or | |
364 | specified along with `--force-with-lease=<refname>:<expect>`, it is | |
365 | a "no-op". | |
366 | + | |
367 | Specifying `--no-force-if-includes` disables this behavior. | |
368 | ||
bf07cc58 | 369 | --repo=<repository>:: |
57b92a77 MG |
370 | This option is equivalent to the <repository> argument. If both |
371 | are specified, the command-line argument takes precedence. | |
dc36f265 | 372 | |
0ed3a111 TR |
373 | -u:: |
374 | --set-upstream:: | |
375 | For every branch that is up to date or successfully pushed, add | |
376 | upstream (tracking) reference, used by argument-less | |
377 | linkgit:git-pull[1] and other commands. For more information, | |
ae9f6311 | 378 | see `branch.<name>.merge` in linkgit:git-config[1]. |
0ed3a111 | 379 | |
0460ed2c | 380 | --[no-]thin:: |
738820a9 SB |
381 | These options are passed to linkgit:git-send-pack[1]. A thin transfer |
382 | significantly reduces the amount of sent data when the sender and | |
383 | receiver share many of the same objects in common. The default is | |
9e9f132f | 384 | `--thin`. |
dc36f265 | 385 | |
989119d9 JK |
386 | -q:: |
387 | --quiet:: | |
388 | Suppress all output, including the listing of updated refs, | |
78381069 TRC |
389 | unless an error occurs. Progress is not reported to the standard |
390 | error stream. | |
989119d9 | 391 | |
3240240f SB |
392 | -v:: |
393 | --verbose:: | |
dc36f265 JH |
394 | Run verbosely. |
395 | ||
78381069 TRC |
396 | --progress:: |
397 | Progress status is reported on the standard error stream | |
398 | by default when it is attached to a terminal, unless -q | |
399 | is specified. This flag forces progress status even if the | |
400 | standard error stream is not directed to a terminal. | |
989119d9 | 401 | |
b33a15b0 | 402 | --no-recurse-submodules:: |
9c24c874 | 403 | --recurse-submodules=check|on-demand|only|no:: |
b33a15b0 MC |
404 | May be used to make sure all submodule commits used by the |
405 | revisions to be pushed are available on a remote-tracking branch. | |
406 | If 'check' is used Git will verify that all submodule commits that | |
407 | changed in the revisions to be pushed are available on at least one | |
408 | remote of the submodule. If any commits are missing the push will | |
409 | be aborted and exit with non-zero status. If 'on-demand' is used | |
410 | all submodules that changed in the revisions to be pushed will be | |
9c24c874 CW |
411 | pushed. If on-demand was not able to push all necessary revisions it will |
412 | also be aborted and exit with non-zero status. If 'only' is used all | |
e62f779a | 413 | submodules will be pushed while the superproject is left |
9c24c874 CW |
414 | unpushed. A value of 'no' or using `--no-recurse-submodules` can be used |
415 | to override the push.recurseSubmodules configuration variable when no | |
416 | submodule recursion is required. | |
e62f779a JT |
417 | + |
418 | When using 'on-demand' or 'only', if a submodule has a | |
419 | "push.recurseSubmodules={on-demand,only}" or "submodule.recurse" configuration, | |
420 | further recursion will occur. In this case, "only" is treated as "on-demand". | |
d2b17b32 | 421 | |
90d32d1f TR |
422 | --[no-]verify:: |
423 | Toggle the pre-push hook (see linkgit:githooks[5]). The | |
1c262bb7 JK |
424 | default is --verify, giving the hook a chance to prevent the |
425 | push. With --no-verify, the hook is bypassed completely. | |
90d32d1f | 426 | |
c915f11e EW |
427 | -4:: |
428 | --ipv4:: | |
429 | Use IPv4 addresses only, ignoring IPv6 addresses. | |
430 | ||
431 | -6:: | |
432 | --ipv6:: | |
433 | Use IPv6 addresses only, ignoring IPv4 addresses. | |
d2b17b32 | 434 | |
37ba0561 | 435 | include::urls-remotes.txt[] |
eb0362a4 | 436 | |
066a5268 JK |
437 | OUTPUT |
438 | ------ | |
439 | ||
440 | The output of "git push" depends on the transport method used; this | |
2de9b711 | 441 | section describes the output when pushing over the Git protocol (either |
066a5268 JK |
442 | locally or via ssh). |
443 | ||
444 | The status of the push is output in tabular form, with each line | |
445 | representing the status of a single ref. Each line is of the form: | |
446 | ||
447 | ------------------------------- | |
448 | <flag> <summary> <from> -> <to> (<reason>) | |
449 | ------------------------------- | |
450 | ||
1965ff74 LA |
451 | If --porcelain is used, then each line of the output is of the form: |
452 | ||
453 | ------------------------------- | |
454 | <flag> \t <from>:<to> \t <summary> (<reason>) | |
455 | ------------------------------- | |
456 | ||
b7047abc JH |
457 | The status of up-to-date refs is shown only if --porcelain or --verbose |
458 | option is used. | |
459 | ||
066a5268 | 460 | flag:: |
b7047abc JH |
461 | A single character indicating the status of the ref: |
462 | (space);; for a successfully pushed fast-forward; | |
6cf378f0 | 463 | `+`;; for a successful forced update; |
b7047abc JH |
464 | `-`;; for a successfully deleted ref; |
465 | `*`;; for a successfully pushed new ref; | |
466 | `!`;; for a ref that was rejected or failed to push; and | |
467 | `=`;; for a ref that was up to date and did not need pushing. | |
066a5268 JK |
468 | |
469 | summary:: | |
470 | For a successfully pushed ref, the summary shows the old and new | |
471 | values of the ref in a form suitable for using as an argument to | |
472 | `git log` (this is `<old>..<new>` in most cases, and | |
6cf378f0 | 473 | `<old>...<new>` for forced non-fast-forward updates). |
9a9fb5d3 TR |
474 | + |
475 | For a failed update, more details are given: | |
476 | + | |
477 | -- | |
478 | rejected:: | |
479 | Git did not try to send the ref at all, typically because it | |
480 | is not a fast-forward and you did not force the update. | |
481 | ||
482 | remote rejected:: | |
483 | The remote end refused the update. Usually caused by a hook | |
484 | on the remote side, or because the remote repository has one | |
485 | of the following safety options in effect: | |
486 | `receive.denyCurrentBranch` (for pushes to the checked out | |
487 | branch), `receive.denyNonFastForwards` (for forced | |
488 | non-fast-forward updates), `receive.denyDeletes` or | |
489 | `receive.denyDeleteCurrent`. See linkgit:git-config[1]. | |
490 | ||
491 | remote failure:: | |
492 | The remote end did not report the successful update of the ref, | |
493 | perhaps because of a temporary error on the remote side, a | |
494 | break in the network connection, or other transient error. | |
495 | -- | |
066a5268 JK |
496 | |
497 | from:: | |
498 | The name of the local ref being pushed, minus its | |
499 | `refs/<type>/` prefix. In the case of deletion, the | |
500 | name of the local ref is omitted. | |
501 | ||
502 | to:: | |
503 | The name of the remote ref being updated, minus its | |
504 | `refs/<type>/` prefix. | |
505 | ||
506 | reason:: | |
507 | A human-readable explanation. In the case of successfully pushed | |
508 | refs, no explanation is needed. For a failed ref, the reason for | |
509 | failure is described. | |
bb9fca80 | 510 | |
76a8788c | 511 | NOTE ABOUT FAST-FORWARDS |
07436e43 MM |
512 | ------------------------ |
513 | ||
514 | When an update changes a branch (or more in general, a ref) that used to | |
515 | point at commit A to point at another commit B, it is called a | |
516 | fast-forward update if and only if B is a descendant of A. | |
517 | ||
518 | In a fast-forward update from A to B, the set of commits that the original | |
519 | commit A built on top of is a subset of the commits the new commit B | |
520 | builds on top of. Hence, it does not lose any history. | |
521 | ||
522 | In contrast, a non-fast-forward update will lose history. For example, | |
523 | suppose you and somebody else started at the same commit X, and you built | |
524 | a history leading to commit B while the other person built a history | |
525 | leading to commit A. The history looks like this: | |
526 | ||
527 | ---------------- | |
528 | ||
529 | B | |
530 | / | |
531 | ---X---A | |
532 | ||
533 | ---------------- | |
534 | ||
535 | Further suppose that the other person already pushed changes leading to A | |
6b6e063c MS |
536 | back to the original repository from which you two obtained the original |
537 | commit X. | |
07436e43 MM |
538 | |
539 | The push done by the other person updated the branch that used to point at | |
540 | commit X to point at commit A. It is a fast-forward. | |
541 | ||
542 | But if you try to push, you will attempt to update the branch (that | |
543 | now points at A) with commit B. This does _not_ fast-forward. If you did | |
544 | so, the changes introduced by commit A will be lost, because everybody | |
545 | will now start building on top of B. | |
546 | ||
547 | The command by default does not allow an update that is not a fast-forward | |
548 | to prevent such loss of history. | |
549 | ||
a58088ab | 550 | If you do not want to lose your work (history from X to B) or the work by |
07436e43 MM |
551 | the other person (history from X to A), you would need to first fetch the |
552 | history from the repository, create a history that contains changes done | |
553 | by both parties, and push the result back. | |
554 | ||
555 | You can perform "git pull", resolve potential conflicts, and "git push" | |
556 | the result. A "git pull" will create a merge commit C between commits A | |
557 | and B. | |
558 | ||
559 | ---------------- | |
560 | ||
561 | B---C | |
562 | / / | |
563 | ---X---A | |
564 | ||
565 | ---------------- | |
566 | ||
567 | Updating A with the resulting merge commit will fast-forward and your | |
568 | push will be accepted. | |
569 | ||
570 | Alternatively, you can rebase your change between X and B on top of A, | |
571 | with "git pull --rebase", and push the result back. The rebase will | |
572 | create a new commit D that builds the change between X and B on top of | |
573 | A. | |
574 | ||
575 | ---------------- | |
576 | ||
577 | B D | |
578 | / / | |
579 | ---X---A | |
580 | ||
581 | ---------------- | |
582 | ||
583 | Again, updating A with this commit will fast-forward and your push will be | |
584 | accepted. | |
585 | ||
586 | There is another common situation where you may encounter non-fast-forward | |
587 | rejection when you try to push, and it is possible even when you are | |
588 | pushing into a repository nobody else pushes into. After you push commit | |
589 | A yourself (in the first picture in this section), replace it with "git | |
590 | commit --amend" to produce commit B, and you try to push it out, because | |
591 | forgot that you have pushed A out already. In such a case, and only if | |
592 | you are certain that nobody in the meantime fetched your earlier commit A | |
593 | (and started building on top of it), you can run "git push --force" to | |
594 | overwrite it. In other words, "git push --force" is a method reserved for | |
595 | a case where you do mean to lose history. | |
596 | ||
597 | ||
76a8788c | 598 | EXAMPLES |
bb9fca80 JH |
599 | -------- |
600 | ||
5d2fc913 | 601 | `git push`:: |
d6aba61f CJ |
602 | Works like `git push <remote>`, where <remote> is the |
603 | current branch's remote (or `origin`, if no remote is | |
604 | configured for the current branch). | |
605 | ||
5d2fc913 | 606 | `git push origin`:: |
b2ed944a | 607 | Without additional configuration, pushes the current branch to |
4c8e3dca | 608 | the configured upstream (`branch.<name>.merge` configuration |
b2ed944a JH |
609 | variable) if it has the same name as the current branch, and |
610 | errors out without pushing otherwise. | |
d6aba61f CJ |
611 | + |
612 | The default behavior of this command when no <refspec> is given can be | |
1ec6f488 RR |
613 | configured by setting the `push` option of the remote, or the `push.default` |
614 | configuration variable. | |
d6aba61f CJ |
615 | + |
616 | For example, to default to pushing only the current branch to `origin` | |
617 | use `git config remote.origin.push HEAD`. Any valid <refspec> (like | |
618 | the ones in the examples below) can be configured as the default for | |
619 | `git push origin`. | |
620 | ||
5d2fc913 | 621 | `git push origin :`:: |
d6aba61f CJ |
622 | Push "matching" branches to `origin`. See |
623 | <refspec> in the <<OPTIONS,OPTIONS>> section above for a | |
624 | description of "matching" branches. | |
625 | ||
5d2fc913 | 626 | `git push origin master`:: |
bb9fca80 JH |
627 | Find a ref that matches `master` in the source repository |
628 | (most likely, it would find `refs/heads/master`), and update | |
629 | the same ref (e.g. `refs/heads/master`) in `origin` repository | |
491b1b11 SV |
630 | with it. If `master` did not exist remotely, it would be |
631 | created. | |
bb9fca80 | 632 | |
5d2fc913 | 633 | `git push origin HEAD`:: |
17507832 AM |
634 | A handy way to push the current branch to the same name on the |
635 | remote. | |
bb9fca80 | 636 | |
b48990e7 | 637 | `git push mothership master:satellite/master dev:satellite/dev`:: |
2c9693bd AMS |
638 | Use the source ref that matches `master` (e.g. `refs/heads/master`) |
639 | to update the ref that matches `satellite/master` (most probably | |
b48990e7 | 640 | `refs/remotes/satellite/master`) in the `mothership` repository; |
2c9693bd | 641 | do the same for `dev` and `satellite/dev`. |
b48990e7 | 642 | + |
2219c09e ÆAB |
643 | See the section describing `<refspec>...` above for a discussion of |
644 | the matching semantics. | |
645 | + | |
b48990e7 JH |
646 | This is to emulate `git fetch` run on the `mothership` using `git |
647 | push` that is run in the opposite direction in order to integrate | |
648 | the work done on `satellite`, and is often necessary when you can | |
649 | only make connection in one way (i.e. satellite can ssh into | |
650 | mothership but mothership cannot initiate connection to satellite | |
651 | because the latter is behind a firewall or does not run sshd). | |
652 | + | |
653 | After running this `git push` on the `satellite` machine, you would | |
654 | ssh into the `mothership` and run `git merge` there to complete the | |
655 | emulation of `git pull` that were run on `mothership` to pull changes | |
656 | made on `satellite`. | |
bb9fca80 | 657 | |
5d2fc913 | 658 | `git push origin HEAD:master`:: |
17507832 AM |
659 | Push the current branch to the remote ref matching `master` in the |
660 | `origin` repository. This form is convenient to push the current | |
661 | branch without thinking about its local name. | |
662 | ||
5d2fc913 | 663 | `git push origin master:refs/heads/experimental`:: |
4e560158 | 664 | Create the branch `experimental` in the `origin` repository |
491b1b11 SV |
665 | by copying the current `master` branch. This form is only |
666 | needed to create a new branch or tag in the remote repository when | |
667 | the local name and the remote name are different; otherwise, | |
668 | the ref name on its own will work. | |
4e560158 | 669 | |
5d2fc913 | 670 | `git push origin :experimental`:: |
17507832 AM |
671 | Find a ref that matches `experimental` in the `origin` repository |
672 | (e.g. `refs/heads/experimental`), and delete it. | |
673 | ||
6cf378f0 | 674 | `git push origin +dev:master`:: |
149f6ddf | 675 | Update the origin repository's master branch with the dev branch, |
a75d7b54 | 676 | allowing non-fast-forward updates. *This can leave unreferenced |
149f6ddf | 677 | commits dangling in the origin repository.* Consider the |
a75d7b54 | 678 | following situation, where a fast-forward is not possible: |
149f6ddf MB |
679 | + |
680 | ---- | |
681 | o---o---o---A---B origin/master | |
682 | \ | |
683 | X---Y---Z dev | |
684 | ---- | |
685 | + | |
686 | The above command would change the origin repository to | |
687 | + | |
688 | ---- | |
689 | A---B (unnamed branch) | |
690 | / | |
691 | o---o---o---X---Y---Z master | |
692 | ---- | |
693 | + | |
694 | Commits A and B would no longer belong to a branch with a symbolic name, | |
695 | and so would be unreachable. As such, these commits would be removed by | |
696 | a `git gc` command on the origin repository. | |
697 | ||
235ec243 MM |
698 | include::transfer-data-leaks.txt[] |
699 | ||
16f6b0d1 ÆAB |
700 | CONFIGURATION |
701 | ------------- | |
702 | ||
703 | include::includes/cmd-config-section-all.txt[] | |
704 | ||
705 | include::config/push.txt[] | |
706 | ||
7fc9d69f JH |
707 | GIT |
708 | --- | |
9e1f0a85 | 709 | Part of the linkgit:git[1] suite |