1GIT-PUSH(1) Git Manual GIT-PUSH(1)
2
6 git-push - Update remote refs along with associated objects
7
9 git push [--all | --mirror | --tags] [-n | --dry-run] [--receive-pack=<git-receive-pack>]
10 [--repo=<repository>] [-f | --force] [-v | --verbose] [-u | --set-upstream]
11 [<repository> [<refspec>...]]
12
15 Updates remote refs using local refs, while sending objects necessary
16 to complete the given refs.
17 You can make interesting things happen to a repository every time you
19 push into it, by setting up hooks there. See documentation for git-
20 receive-pack(1).
21
23 <repository>
24 The "remote" repository that is destination of a push operation.
25 This parameter can be either a URL (see the section GIT URLS below)
26 or the name of a remote (see the section REMOTES below).
27 <refspec>...
29 The format of a <refspec> parameter is an optional plus +, followed
30 by the source ref <src>, followed by a colon :, followed by the
31 destination ref <dst>. It is used to specify with what <src> object
32 the <dst> ref in the remote repository is to be updated.
33 The <src> is often the name of the branch you would want to push,
35 but it can be any arbitrary "SHA-1 expression", such as master~4 or
36 HEAD (see gitrevisions(7)).
37 The <dst> tells which ref on the remote side is updated with this
39 push. Arbitrary expressions cannot be used here, an actual ref must
40 be named. If :<dst> is omitted, the same ref as <src> will be
41 updated.
42 The object referenced by <src> is used to update the <dst>
44 reference on the remote side, but by default this is only allowed
45 if the update can fast-forward <dst>. By having the optional
46 leading +, you can tell git to update the <dst> ref even when the
47 update is not a fast-forward. This does not attempt to merge <src>
48 into <dst>. See EXAMPLES below for details.
49 tag <tag> means the same as refs/tags/<tag>:refs/tags/<tag>.
51 Pushing an empty <src> allows you to delete the <dst> ref from the
53 remote repository.
54 The special refspec : (or +: to allow non-fast-forward updates)
56 directs git to push "matching" branches: for every branch that
57 exists on the local side, the remote side is updated if a branch of
58 the same name already exists on the remote side. This is the
59 default operation mode if no explicit refspec is found (that is
60 neither on the command line nor in any Push line of the
61 corresponding remotes file---see below).
62 --all
64 Instead of naming each ref to push, specifies that all refs under
65 refs/heads/ be pushed.
66 --mirror
68 Instead of naming each ref to push, specifies that all refs under
69 refs/ (which includes but is not limited to refs/heads/,
70 refs/remotes/, and refs/tags/) be mirrored to the remote
71 repository. Newly created local refs will be pushed to the remote
72 end, locally updated refs will be force updated on the remote end,
73 and deleted refs will be removed from the remote end. This is the
74 default if the configuration option remote.<remote>.mirror is set.
75 -n, --dry-run
77 Do everything except actually send the updates.
78 --porcelain
80 Produce machine-readable output. The output status line for each
81 ref will be tab-separated and sent to stdout instead of stderr. The
82 full symbolic names of the refs will be given.
83 --delete
85 All listed refs are deleted from the remote repository. This is the
86 same as prefixing all refs with a colon.
87 --tags
89 All refs under refs/tags are pushed, in addition to refspecs
90 explicitly listed on the command line.
91 --receive-pack=<git-receive-pack>, --exec=<git-receive-pack>
93 Path to the git-receive-pack program on the remote end. Sometimes
94 useful when pushing to a remote repository over ssh, and you do not
95 have the program in a directory on the default $PATH.
96 -f, --force
98 Usually, the command refuses to update a remote ref that is not an
99 ancestor of the local ref used to overwrite it. This flag disables
100 the check. This can cause the remote repository to lose commits;
101 use it with care.
102 --repo=<repository>
104 This option is only relevant if no <repository> argument is passed
105 in the invocation. In this case, git push derives the remote name
106 from the current branch: If it tracks a remote branch, then that
107 remote repository is pushed to. Otherwise, the name "origin" is
108 used. For this latter case, this option can be used to override the
109 name "origin". In other words, the difference between these two
110 commands
111 git push public #1
113 git push --repo=public #2
114 is that #1 always pushes to "public" whereas #2 pushes to "public"
116 only if the current branch does not track a remote branch. This is
117 useful if you write an alias or script around git push.
118 -u, --set-upstream
120 For every branch that is up to date or successfully pushed, add
121 upstream (tracking) reference, used by argument-less git-pull(1)
122 and other commands. For more information, see branch.<name>.merge
123 in git-config(1).
124 --thin, --no-thin
126 These options are passed to git-send-pack(1). A thin transfer
127 significantly reduces the amount of sent data when the sender and
128 receiver share many of the same objects in common. The default is
129 --thin.
130 -q, --quiet
132 Suppress all output, including the listing of updated refs, unless
133 an error occurs. Progress is not reported to the standard error
134 stream.
135 -v, --verbose
137 Run verbosely.
138 --progress
140 Progress status is reported on the standard error stream by default
141 when it is attached to a terminal, unless -q is specified. This
142 flag forces progress status even if the standard error stream is
143 not directed to a terminal.
144
146 In general, URLs contain information about the transport protocol, the
147 address of the remote server, and the path to the repository. Depending
148 on the transport protocol, some of this information may be absent.
149 Git natively supports ssh, git, http, https, ftp, ftps, and rsync
151 protocols. The following syntaxes may be used with them:
152 · ssh://[user@]host.xz[:port]/path/to/repo.git/
154 · git://host.xz[:port]/path/to/repo.git/
156 · http[s]://host.xz[:port]/path/to/repo.git/
158 · ftp[s]://host.xz[:port]/path/to/repo.git/
160 · rsync://host.xz/path/to/repo.git/
162 An alternative scp-like syntax may also be used with the ssh protocol:
164 · [user@]host.xz:path/to/repo.git/
166 The ssh and git protocols additionally support ~username expansion:
168 · ssh://[user@]host.xz[:port]/~[user]/path/to/repo.git/
170 · git://host.xz[:port]/~[user]/path/to/repo.git/
172 · [user@]host.xz:/~[user]/path/to/repo.git/
174 For local repositories, also supported by git natively, the following
176 syntaxes may be used:
177 · /path/to/repo.git/
179 · file:///path/to/repo.git/
181 These two syntaxes are mostly equivalent, except when cloning, when the
183 former implies --local option. See git-clone(1) for details.
184 When git doesn’t know how to handle a certain transport protocol, it
186 attempts to use the remote-<transport> remote helper, if one exists. To
187 explicitly request a remote helper, the following syntax may be used:
188 · <transport>::<address>
190 where <address> may be a path, a server and path, or an arbitrary
192 URL-like string recognized by the specific remote helper being invoked.
193 See git-remote-helpers(1) for details.
194 If there are a large number of similarly-named remote repositories and
196 you want to use a different format for them (such that the URLs you use
197 will be rewritten into URLs that work), you can create a configuration
198 section of the form:
199 [url "<actual url base>"]
201 insteadOf = <other url base>
202 For example, with this:
205 [url "git://git.host.xz/"]
207 insteadOf = host.xz:/path/to/
208 insteadOf = work:
209 a URL like "work:repo.git" or like "host.xz:/path/to/repo.git" will be
212 rewritten in any context that takes a URL to be
213 "git://git.host.xz/repo.git".
214 If you want to rewrite URLs for push only, you can create a
216 configuration section of the form:
217 [url "<actual url base>"]
219 pushInsteadOf = <other url base>
220 For example, with this:
223 [url "ssh://example.org/"]
225 pushInsteadOf = git://example.org/
226 a URL like "git://example.org/path/to/repo.git" will be rewritten to
229 "ssh://example.org/path/to/repo.git" for pushes, but pulls will still
230 use the original URL.
231
233 The name of one of the following can be used instead of a URL as
234 <repository> argument:
235 · a remote in the git configuration file: $GIT_DIR/config,
237 · a file in the $GIT_DIR/remotes directory, or
239 · a file in the $GIT_DIR/branches directory.
241 All of these also allow you to omit the refspec from the command line
243 because they each contain a refspec which git will use by default.
244 Named remote in configuration file
246 You can choose to provide the name of a remote which you had previously
247 configured using git-remote(1), git-config(1) or even by a manual edit
248 to the $GIT_DIR/config file. The URL of this remote will be used to
249 access the repository. The refspec of this remote will be used by
250 default when you do not provide a refspec on the command line. The
251 entry in the config file would appear like this:
252 [remote "<name>"]
254 url = <url>
255 pushurl = <pushurl>
256 push = <refspec>
257 fetch = <refspec>
258 The <pushurl> is used for pushes only. It is optional and defaults to
261 <url>.
262 Named file in $GIT_DIR/remotes
264 You can choose to provide the name of a file in $GIT_DIR/remotes. The
265 URL in this file will be used to access the repository. The refspec in
266 this file will be used as default when you do not provide a refspec on
267 the command line. This file should have the following format:
268 URL: one of the above URL format
270 Push: <refspec>
271 Pull: <refspec>
272 Push: lines are used by git push and Pull: lines are used by git pull
275 and git fetch. Multiple Push: and Pull: lines may be specified for
276 additional branch mappings.
277 Named file in $GIT_DIR/branches
279 You can choose to provide the name of a file in $GIT_DIR/branches. The
280 URL in this file will be used to access the repository. This file
281 should have the following format:
282 <url>#<head>
284 <url> is required; #<head> is optional.
287 Depending on the operation, git will use one of the following refspecs,
289 if you don’t provide one on the command line. <branch> is the name of
290 this file in $GIT_DIR/branches and <head> defaults to master.
291 git fetch uses:
293 refs/heads/<head>:refs/heads/<branch>
295 git push uses:
298 HEAD:refs/heads/<head>
300
303 The output of "git push" depends on the transport method used; this
304 section describes the output when pushing over the git protocol (either
305 locally or via ssh).
306 The status of the push is output in tabular form, with each line
308 representing the status of a single ref. Each line is of the form:
309 <flag> <summary> <from> -> <to> (<reason>)
311 If --porcelain is used, then each line of the output is of the form:
314 <flag> \t <from>:<to> \t <summary> (<reason>)
316 The status of up-to-date refs is shown only if --porcelain or --verbose
319 option is used.
320 flag
322 A single character indicating the status of the ref:
323 (space)
325 for a successfully pushed fast-forward;
326 +
328 for a successful forced update;
329 -
331 for a successfully deleted ref;
332 *
334 for a successfully pushed new ref;
335 !
337 for a ref that was rejected or failed to push; and
338 =
340 for a ref that was up to date and did not need pushing.
341 summary
343 For a successfully pushed ref, the summary shows the old and new
344 values of the ref in a form suitable for using as an argument to
345 git log (this is <old>..<new> in most cases, and <old>...<new> for
346 forced non-fast-forward updates).
347 For a failed update, more details are given:
349 rejected
351 Git did not try to send the ref at all, typically because it is
352 not a fast-forward and you did not force the update.
353 remote rejected
355 The remote end refused the update. Usually caused by a hook on
356 the remote side, or because the remote repository has one of
357 the following safety options in effect:
358 receive.denyCurrentBranch (for pushes to the checked out
359 branch), receive.denyNonFastForwards (for forced
360 non-fast-forward updates), receive.denyDeletes or
361 receive.denyDeleteCurrent. See git-config(1).
362 remote failure
364 The remote end did not report the successful update of the ref,
365 perhaps because of a temporary error on the remote side, a
366 break in the network connection, or other transient error.
367 from
369 The name of the local ref being pushed, minus its refs/<type>/
370 prefix. In the case of deletion, the name of the local ref is
371 omitted.
372 to
374 The name of the remote ref being updated, minus its refs/<type>/
375 prefix.
376 reason
378 A human-readable explanation. In the case of successfully pushed
379 refs, no explanation is needed. For a failed ref, the reason for
380 failure is described.
381
383 When an update changes a branch (or more in general, a ref) that used
384 to point at commit A to point at another commit B, it is called a
385 fast-forward update if and only if B is a descendant of A.
386 In a fast-forward update from A to B, the set of commits that the
388 original commit A built on top of is a subset of the commits the new
389 commit B builds on top of. Hence, it does not lose any history.
390 In contrast, a non-fast-forward update will lose history. For example,
392 suppose you and somebody else started at the same commit X, and you
393 built a history leading to commit B while the other person built a
394 history leading to commit A. The history looks like this:
395 B
397 /
398 ---X---A
399 Further suppose that the other person already pushed changes leading to
402 A back to the original repository you two obtained the original commit
403 X.
404 The push done by the other person updated the branch that used to point
406 at commit X to point at commit A. It is a fast-forward.
407 But if you try to push, you will attempt to update the branch (that now
409 points at A) with commit B. This does not fast-forward. If you did so,
410 the changes introduced by commit A will be lost, because everybody will
411 now start building on top of B.
412 The command by default does not allow an update that is not a
414 fast-forward to prevent such loss of history.
415 If you do not want to lose your work (history from X to B) nor the work
417 by the other person (history from X to A), you would need to first
418 fetch the history from the repository, create a history that contains
419 changes done by both parties, and push the result back.
420 You can perform "git pull", resolve potential conflicts, and "git push"
422 the result. A "git pull" will create a merge commit C between commits A
423 and B.
424 B---C
426 / /
427 ---X---A
428 Updating A with the resulting merge commit will fast-forward and your
431 push will be accepted.
432 Alternatively, you can rebase your change between X and B on top of A,
434 with "git pull --rebase", and push the result back. The rebase will
435 create a new commit D that builds the change between X and B on top of
436 A.
437 B D
439 / /
440 ---X---A
441 Again, updating A with this commit will fast-forward and your push will
444 be accepted.
445 There is another common situation where you may encounter
447 non-fast-forward rejection when you try to push, and it is possible
448 even when you are pushing into a repository nobody else pushes into.
449 After you push commit A yourself (in the first picture in this
450 section), replace it with "git commit --amend" to produce commit B, and
451 you try to push it out, because forgot that you have pushed A out
452 already. In such a case, and only if you are certain that nobody in the
453 meantime fetched your earlier commit A (and started building on top of
454 it), you can run "git push --force" to overwrite it. In other words,
455 "git push --force" is a method reserved for a case where you do mean to
456 lose history.
457
459 git push
460 Works like git push <remote>, where <remote> is the current
461 branch’s remote (or origin, if no remote is configured for the
462 current branch).
463 git push origin
465 Without additional configuration, works like git push origin :.
466 The default behavior of this command when no <refspec> is given can
468 be configured by setting the push option of the remote.
469 For example, to default to pushing only the current branch to
471 origin use git config remote.origin.push HEAD. Any valid <refspec>
472 (like the ones in the examples below) can be configured as the
473 default for git push origin.
474 git push origin
476 Push "matching" branches to origin. See <refspec> in the
477 OPTIONS section above for a description of "matching" branches.
478 git push origin master
480 Find a ref that matches master in the source repository (most
481 likely, it would find refs/heads/master), and update the same ref
482 (e.g. refs/heads/master) in origin repository with it. If master
483 did not exist remotely, it would be created.
484 git push origin HEAD
486 A handy way to push the current branch to the same name on the
487 remote.
488 git push origin master:satellite/master dev:satellite/dev
490 Use the source ref that matches master (e.g. refs/heads/master) to
491 update the ref that matches satellite/master (most probably
492 refs/remotes/satellite/master) in the origin repository, then do
493 the same for dev and satellite/dev.
494 git push origin HEAD:master
496 Push the current branch to the remote ref matching master in the
497 origin repository. This form is convenient to push the current
498 branch without thinking about its local name.
499 git push origin master:refs/heads/experimental
501 Create the branch experimental in the origin repository by copying
502 the current master branch. This form is only needed to create a new
503 branch or tag in the remote repository when the local name and the
504 remote name are different; otherwise, the ref name on its own will
505 work.
506 git push origin :experimental
508 Find a ref that matches experimental in the origin repository (e.g.
509 refs/heads/experimental), and delete it.
510 git push origin +dev:master
512 Update the origin repository’s master branch with the dev branch,
513 allowing non-fast-forward updates. This can leave unreferenced
514 commits dangling in the origin repository. Consider the following
515 situation, where a fast-forward is not possible:
516 o---o---o---A---B origin/master
518 \
519 X---Y---Z dev
520 The above command would change the origin repository to
522 A---B (unnamed branch)
524 /
525 o---o---o---X---Y---Z master
526 Commits A and B would no longer belong to a branch with a symbolic
528 name, and so would be unreachable. As such, these commits would be
529 removed by a git gc command on the origin repository.
530
532 Written by Junio C Hamano <gitster@pobox.com[1]>, later rewritten in C
533 by Linus Torvalds <torvalds@osdl.org[2]>
534
536 Documentation by Junio C Hamano and the git-list
537 <git@vger.kernel.org[3]>.
538
540 Part of the git(1) suite
541
543 1. gitster@pobox.com
544 mailto:gitster@pobox.com
545 2. torvalds@osdl.org
547 mailto:torvalds@osdl.org
548 3. git@vger.kernel.org
550 mailto:git@vger.kernel.org
551Git 1.7.4.4 04/11/2011 GIT-PUSH(1)