]>
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] |
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 | |
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 | |
7fc9d69f | 26 | |
d6aba61f CJ |
27 | OPTIONS[[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 |
42 | The <src> is often the name of the branch you would want to push, but |
43 | it can be any arbitrary "SHA-1 expression", such as `master~4` or | |
44 | `HEAD` (see linkgit:git-rev-parse[1]). | |
3598a308 | 45 | + |
80391846 AM |
46 | The <dst> tells which ref on the remote side is updated with this |
47 | push. Arbitrary expressions cannot be used here, an actual ref must | |
48 | be named. If `:`<dst> is omitted, the same ref as <src> will be | |
49 | updated. | |
3598a308 | 50 | + |
149f6ddf MB |
51 | The object referenced by <src> is used to update the <dst> reference |
52 | on the remote side, but by default this is only allowed if the | |
53 | update can fast forward <dst>. By having the optional leading `{plus}`, | |
54 | you can tell git to update the <dst> ref even when the update is not a | |
55 | fast forward. This does *not* attempt to merge <src> into <dst>. See | |
56 | EXAMPLES below for details. | |
3598a308 | 57 | + |
80391846 | 58 | `tag <tag>` means the same as `refs/tags/<tag>:refs/tags/<tag>`. |
25fb6290 JH |
59 | + |
60 | Pushing an empty <src> allows you to delete the <dst> ref from | |
61 | the remote repository. | |
a83619d6 | 62 | + |
149f6ddf | 63 | The special refspec `:` (or `{plus}:` to allow non-fast forward updates) |
89edd5a9 AM |
64 | directs git to push "matching" branches: for every branch that exists on |
65 | the local side, the remote side is updated if a branch of the same name | |
a83619d6 PB |
66 | already exists on the remote side. This is the default operation mode |
67 | if no explicit refspec is found (that is neither on the command line | |
68 | nor 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 | ||
1965ff74 LA |
88 | --porcelain:: |
89 | Produce machine-readable output. The output status line for each ref | |
90 | will be tab-separated and sent to stdout instead of stderr. The full | |
91 | symbolic names of the refs will be given. | |
92 | ||
3240240f | 93 | --tags:: |
42301e34 JH |
94 | All refs under `$GIT_DIR/refs/tags` are pushed, in |
95 | addition to refspecs explicitly listed on the command | |
96 | line. | |
97 | ||
3240240f | 98 | --receive-pack=<git-receive-pack>:: |
4fc988ef | 99 | --exec=<git-receive-pack>:: |
ba020ef5 | 100 | Path to the 'git-receive-pack' program on the remote |
5214f770 UKK |
101 | end. Sometimes useful when pushing to a remote |
102 | repository over ssh, and you do not have the program in | |
103 | a directory on the default $PATH. | |
104 | ||
3240240f SB |
105 | -f:: |
106 | --force:: | |
f0fff36e | 107 | Usually, the command refuses to update a remote ref that is |
64a476e6 | 108 | not an ancestor of the local ref used to overwrite it. |
f0fff36e BF |
109 | This flag disables the check. This can cause the |
110 | remote repository to lose commits; use it with care. | |
7fc9d69f | 111 | |
bf07cc58 JS |
112 | --repo=<repository>:: |
113 | This option is only relevant if no <repository> argument is | |
114 | passed in the invocation. In this case, 'git-push' derives the | |
115 | remote name from the current branch: If it tracks a remote | |
116 | branch, then that remote repository is pushed to. Otherwise, | |
117 | the name "origin" is used. For this latter case, this option | |
118 | can be used to override the name "origin". In other words, | |
119 | the difference between these two commands | |
120 | + | |
121 | -------------------------- | |
122 | git push public #1 | |
123 | git push --repo=public #2 | |
124 | -------------------------- | |
125 | + | |
126 | is that #1 always pushes to "public" whereas #2 pushes to "public" | |
127 | only if the current branch does not track a remote branch. This is | |
128 | useful if you write an alias or script around 'git-push'. | |
dc36f265 | 129 | |
3240240f SB |
130 | --thin:: |
131 | --no-thin:: | |
ba020ef5 | 132 | These options are passed to 'git-send-pack'. Thin |
dc36f265 JH |
133 | transfer spends extra cycles to minimize the number of |
134 | objects to be sent and meant to be used on slower connection. | |
135 | ||
3240240f SB |
136 | -v:: |
137 | --verbose:: | |
dc36f265 JH |
138 | Run verbosely. |
139 | ||
37ba0561 | 140 | include::urls-remotes.txt[] |
eb0362a4 | 141 | |
066a5268 JK |
142 | OUTPUT |
143 | ------ | |
144 | ||
145 | The output of "git push" depends on the transport method used; this | |
146 | section describes the output when pushing over the git protocol (either | |
147 | locally or via ssh). | |
148 | ||
149 | The status of the push is output in tabular form, with each line | |
150 | representing the status of a single ref. Each line is of the form: | |
151 | ||
152 | ------------------------------- | |
153 | <flag> <summary> <from> -> <to> (<reason>) | |
154 | ------------------------------- | |
155 | ||
1965ff74 LA |
156 | If --porcelain is used, then each line of the output is of the form: |
157 | ||
158 | ------------------------------- | |
159 | <flag> \t <from>:<to> \t <summary> (<reason>) | |
160 | ------------------------------- | |
161 | ||
066a5268 JK |
162 | flag:: |
163 | A single character indicating the status of the ref. This is | |
164 | blank for a successfully pushed ref, `!` for a ref that was | |
165 | rejected or failed to push, and '=' for a ref that was up to | |
166 | date and did not need pushing (note that the status of up to | |
167 | date refs is shown only when `git push` is running verbosely). | |
168 | ||
169 | summary:: | |
170 | For a successfully pushed ref, the summary shows the old and new | |
171 | values of the ref in a form suitable for using as an argument to | |
172 | `git log` (this is `<old>..<new>` in most cases, and | |
173 | `<old>...<new>` for forced non-fast forward updates). For a | |
174 | failed update, more details are given for the failure. | |
175 | The string `rejected` indicates that git did not try to send the | |
176 | ref at all (typically because it is not a fast forward). The | |
177 | string `remote rejected` indicates that the remote end refused | |
178 | the update; this rejection is typically caused by a hook on the | |
179 | remote side. The string `remote failure` indicates that the | |
180 | remote end did not report the successful update of the ref | |
181 | (perhaps because of a temporary error on the remote side, a | |
182 | break in the network connection, or other transient error). | |
183 | ||
184 | from:: | |
185 | The name of the local ref being pushed, minus its | |
186 | `refs/<type>/` prefix. In the case of deletion, the | |
187 | name of the local ref is omitted. | |
188 | ||
189 | to:: | |
190 | The name of the remote ref being updated, minus its | |
191 | `refs/<type>/` prefix. | |
192 | ||
193 | reason:: | |
194 | A human-readable explanation. In the case of successfully pushed | |
195 | refs, no explanation is needed. For a failed ref, the reason for | |
196 | failure is described. | |
bb9fca80 | 197 | |
07436e43 MM |
198 | Note about fast-forwards |
199 | ------------------------ | |
200 | ||
201 | When an update changes a branch (or more in general, a ref) that used to | |
202 | point at commit A to point at another commit B, it is called a | |
203 | fast-forward update if and only if B is a descendant of A. | |
204 | ||
205 | In a fast-forward update from A to B, the set of commits that the original | |
206 | commit A built on top of is a subset of the commits the new commit B | |
207 | builds on top of. Hence, it does not lose any history. | |
208 | ||
209 | In contrast, a non-fast-forward update will lose history. For example, | |
210 | suppose you and somebody else started at the same commit X, and you built | |
211 | a history leading to commit B while the other person built a history | |
212 | leading to commit A. The history looks like this: | |
213 | ||
214 | ---------------- | |
215 | ||
216 | B | |
217 | / | |
218 | ---X---A | |
219 | ||
220 | ---------------- | |
221 | ||
222 | Further suppose that the other person already pushed changes leading to A | |
223 | back to the original repository you two obtained the original commit X. | |
224 | ||
225 | The push done by the other person updated the branch that used to point at | |
226 | commit X to point at commit A. It is a fast-forward. | |
227 | ||
228 | But if you try to push, you will attempt to update the branch (that | |
229 | now points at A) with commit B. This does _not_ fast-forward. If you did | |
230 | so, the changes introduced by commit A will be lost, because everybody | |
231 | will now start building on top of B. | |
232 | ||
233 | The command by default does not allow an update that is not a fast-forward | |
234 | to prevent such loss of history. | |
235 | ||
236 | If you do not want to lose your work (history from X to B) nor the work by | |
237 | the other person (history from X to A), you would need to first fetch the | |
238 | history from the repository, create a history that contains changes done | |
239 | by both parties, and push the result back. | |
240 | ||
241 | You can perform "git pull", resolve potential conflicts, and "git push" | |
242 | the result. A "git pull" will create a merge commit C between commits A | |
243 | and B. | |
244 | ||
245 | ---------------- | |
246 | ||
247 | B---C | |
248 | / / | |
249 | ---X---A | |
250 | ||
251 | ---------------- | |
252 | ||
253 | Updating A with the resulting merge commit will fast-forward and your | |
254 | push will be accepted. | |
255 | ||
256 | Alternatively, you can rebase your change between X and B on top of A, | |
257 | with "git pull --rebase", and push the result back. The rebase will | |
258 | create a new commit D that builds the change between X and B on top of | |
259 | A. | |
260 | ||
261 | ---------------- | |
262 | ||
263 | B D | |
264 | / / | |
265 | ---X---A | |
266 | ||
267 | ---------------- | |
268 | ||
269 | Again, updating A with this commit will fast-forward and your push will be | |
270 | accepted. | |
271 | ||
272 | There is another common situation where you may encounter non-fast-forward | |
273 | rejection when you try to push, and it is possible even when you are | |
274 | pushing into a repository nobody else pushes into. After you push commit | |
275 | A yourself (in the first picture in this section), replace it with "git | |
276 | commit --amend" to produce commit B, and you try to push it out, because | |
277 | forgot that you have pushed A out already. In such a case, and only if | |
278 | you are certain that nobody in the meantime fetched your earlier commit A | |
279 | (and started building on top of it), you can run "git push --force" to | |
280 | overwrite it. In other words, "git push --force" is a method reserved for | |
281 | a case where you do mean to lose history. | |
282 | ||
283 | ||
bb9fca80 JH |
284 | Examples |
285 | -------- | |
286 | ||
d6aba61f CJ |
287 | git push:: |
288 | Works like `git push <remote>`, where <remote> is the | |
289 | current branch's remote (or `origin`, if no remote is | |
290 | configured for the current branch). | |
291 | ||
292 | git push origin:: | |
293 | Without additional configuration, works like | |
294 | `git push origin :`. | |
295 | + | |
296 | The default behavior of this command when no <refspec> is given can be | |
297 | configured by setting the `push` option of the remote. | |
298 | + | |
299 | For example, to default to pushing only the current branch to `origin` | |
300 | use `git config remote.origin.push HEAD`. Any valid <refspec> (like | |
301 | the ones in the examples below) can be configured as the default for | |
302 | `git push origin`. | |
303 | ||
304 | git push origin ::: | |
305 | Push "matching" branches to `origin`. See | |
306 | <refspec> in the <<OPTIONS,OPTIONS>> section above for a | |
307 | description of "matching" branches. | |
308 | ||
bb9fca80 JH |
309 | git push origin master:: |
310 | Find a ref that matches `master` in the source repository | |
311 | (most likely, it would find `refs/heads/master`), and update | |
312 | the same ref (e.g. `refs/heads/master`) in `origin` repository | |
491b1b11 SV |
313 | with it. If `master` did not exist remotely, it would be |
314 | created. | |
bb9fca80 | 315 | |
17507832 AM |
316 | git push origin HEAD:: |
317 | A handy way to push the current branch to the same name on the | |
318 | remote. | |
bb9fca80 | 319 | |
2c9693bd AMS |
320 | git push origin master:satellite/master dev:satellite/dev:: |
321 | Use the source ref that matches `master` (e.g. `refs/heads/master`) | |
322 | to update the ref that matches `satellite/master` (most probably | |
323 | `refs/remotes/satellite/master`) in the `origin` repository, then | |
324 | do the same for `dev` and `satellite/dev`. | |
bb9fca80 | 325 | |
17507832 AM |
326 | git push origin HEAD:master:: |
327 | Push the current branch to the remote ref matching `master` in the | |
328 | `origin` repository. This form is convenient to push the current | |
329 | branch without thinking about its local name. | |
330 | ||
4e560158 SP |
331 | git push origin master:refs/heads/experimental:: |
332 | Create the branch `experimental` in the `origin` repository | |
491b1b11 SV |
333 | by copying the current `master` branch. This form is only |
334 | needed to create a new branch or tag in the remote repository when | |
335 | the local name and the remote name are different; otherwise, | |
336 | the ref name on its own will work. | |
4e560158 | 337 | |
17507832 AM |
338 | git push origin :experimental:: |
339 | Find a ref that matches `experimental` in the `origin` repository | |
340 | (e.g. `refs/heads/experimental`), and delete it. | |
341 | ||
149f6ddf MB |
342 | git push origin {plus}dev:master:: |
343 | Update the origin repository's master branch with the dev branch, | |
344 | allowing non-fast forward updates. *This can leave unreferenced | |
345 | commits dangling in the origin repository.* Consider the | |
346 | following situation, where a fast forward is not possible: | |
347 | + | |
348 | ---- | |
349 | o---o---o---A---B origin/master | |
350 | \ | |
351 | X---Y---Z dev | |
352 | ---- | |
353 | + | |
354 | The above command would change the origin repository to | |
355 | + | |
356 | ---- | |
357 | A---B (unnamed branch) | |
358 | / | |
359 | o---o---o---X---Y---Z master | |
360 | ---- | |
361 | + | |
362 | Commits A and B would no longer belong to a branch with a symbolic name, | |
363 | and so would be unreachable. As such, these commits would be removed by | |
364 | a `git gc` command on the origin repository. | |
365 | ||
17507832 | 366 | |
7fc9d69f JH |
367 | Author |
368 | ------ | |
59eb68aa | 369 | Written by Junio C Hamano <gitster@pobox.com>, later rewritten in C |
25fb6290 | 370 | by Linus Torvalds <torvalds@osdl.org> |
7fc9d69f JH |
371 | |
372 | Documentation | |
373 | -------------- | |
374 | Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. | |
375 | ||
376 | GIT | |
377 | --- | |
9e1f0a85 | 378 | Part of the linkgit:git[1] suite |