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 git-rev-parse(1)).
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 respositories, 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). For a failed update, more details
347 are given for the failure. The string rejected indicates that git
348 did not try to send the ref at all (typically because it is not a
349 fast-forward). The string remote rejected indicates that the remote
350 end refused the update; this rejection is typically caused by a
351 hook on the remote side. The string remote failure indicates that
352 the remote end did not report the successful update of the ref
353 (perhaps because of a temporary error on the remote side, a break
354 in the network connection, or other transient error).
355 from
357 The name of the local ref being pushed, minus its refs/<type>/
358 prefix. In the case of deletion, the name of the local ref is
359 omitted.
360 to
362 The name of the remote ref being updated, minus its refs/<type>/
363 prefix.
364 reason
366 A human-readable explanation. In the case of successfully pushed
367 refs, no explanation is needed. For a failed ref, the reason for
368 failure is described.
369
371 When an update changes a branch (or more in general, a ref) that used
372 to point at commit A to point at another commit B, it is called a
373 fast-forward update if and only if B is a descendant of A.
374 In a fast-forward update from A to B, the set of commits that the
376 original commit A built on top of is a subset of the commits the new
377 commit B builds on top of. Hence, it does not lose any history.
378 In contrast, a non-fast-forward update will lose history. For example,
380 suppose you and somebody else started at the same commit X, and you
381 built a history leading to commit B while the other person built a
382 history leading to commit A. The history looks like this:
383 B
385 /
386 ---X---A
387 Further suppose that the other person already pushed changes leading to
390 A back to the original repository you two obtained the original commit
391 X.
392 The push done by the other person updated the branch that used to point
394 at commit X to point at commit A. It is a fast-forward.
395 But if you try to push, you will attempt to update the branch (that now
397 points at A) with commit B. This does not fast-forward. If you did so,
398 the changes introduced by commit A will be lost, because everybody will
399 now start building on top of B.
400 The command by default does not allow an update that is not a
402 fast-forward to prevent such loss of history.
403 If you do not want to lose your work (history from X to B) nor the work
405 by the other person (history from X to A), you would need to first
406 fetch the history from the repository, create a history that contains
407 changes done by both parties, and push the result back.
408 You can perform "git pull", resolve potential conflicts, and "git push"
410 the result. A "git pull" will create a merge commit C between commits A
411 and B.
412 B---C
414 / /
415 ---X---A
416 Updating A with the resulting merge commit will fast-forward and your
419 push will be accepted.
420 Alternatively, you can rebase your change between X and B on top of A,
422 with "git pull --rebase", and push the result back. The rebase will
423 create a new commit D that builds the change between X and B on top of
424 A.
425 B D
427 / /
428 ---X---A
429 Again, updating A with this commit will fast-forward and your push will
432 be accepted.
433 There is another common situation where you may encounter
435 non-fast-forward rejection when you try to push, and it is possible
436 even when you are pushing into a repository nobody else pushes into.
437 After you push commit A yourself (in the first picture in this
438 section), replace it with "git commit --amend" to produce commit B, and
439 you try to push it out, because forgot that you have pushed A out
440 already. In such a case, and only if you are certain that nobody in the
441 meantime fetched your earlier commit A (and started building on top of
442 it), you can run "git push --force" to overwrite it. In other words,
443 "git push --force" is a method reserved for a case where you do mean to
444 lose history.
445
447 git push
448 Works like git push <remote>, where <remote> is the current
449 branch’s remote (or origin, if no remote is configured for the
450 current branch).
451 git push origin
453 Without additional configuration, works like git push origin :.
454 The default behavior of this command when no <refspec> is given can
456 be configured by setting the push option of the remote.
457 For example, to default to pushing only the current branch to
459 origin use git config remote.origin.push HEAD. Any valid <refspec>
460 (like the ones in the examples below) can be configured as the
461 default for git push origin.
462 git push origin
464 Push "matching" branches to origin. See <refspec> in the
465 OPTIONS section above for a description of "matching" branches.
466 git push origin master
468 Find a ref that matches master in the source repository (most
469 likely, it would find refs/heads/master), and update the same ref
470 (e.g. refs/heads/master) in origin repository with it. If master
471 did not exist remotely, it would be created.
472 git push origin HEAD
474 A handy way to push the current branch to the same name on the
475 remote.
476 git push origin master:satellite/master dev:satellite/dev
478 Use the source ref that matches master (e.g. refs/heads/master) to
479 update the ref that matches satellite/master (most probably
480 refs/remotes/satellite/master) in the origin repository, then do
481 the same for dev and satellite/dev.
482 git push origin HEAD:master
484 Push the current branch to the remote ref matching master in the
485 origin repository. This form is convenient to push the current
486 branch without thinking about its local name.
487 git push origin master:refs/heads/experimental
489 Create the branch experimental in the origin repository by copying
490 the current master branch. This form is only needed to create a new
491 branch or tag in the remote repository when the local name and the
492 remote name are different; otherwise, the ref name on its own will
493 work.
494 git push origin :experimental
496 Find a ref that matches experimental in the origin repository (e.g.
497 refs/heads/experimental), and delete it.
498 git push origin +dev:master
500 Update the origin repository’s master branch with the dev branch,
501 allowing non-fast-forward updates. This can leave unreferenced
502 commits dangling in the origin repository. Consider the following
503 situation, where a fast-forward is not possible:
504 o---o---o---A---B origin/master
506 \
507 X---Y---Z dev
508 The above command would change the origin repository to
510 A---B (unnamed branch)
512 /
513 o---o---o---X---Y---Z master
514 Commits A and B would no longer belong to a branch with a symbolic
516 name, and so would be unreachable. As such, these commits would be
517 removed by a git gc command on the origin repository.
518
520 Written by Junio C Hamano <gitster@pobox.com[1]>, later rewritten in C
521 by Linus Torvalds <torvalds@osdl.org[2]>
522
524 Documentation by Junio C Hamano and the git-list
525 <git@vger.kernel.org[3]>.
526
528 Part of the git(1) suite
529
531 1. gitster@pobox.com
532 mailto:gitster@pobox.com
533 2. torvalds@osdl.org
535 mailto:torvalds@osdl.org
536 3. git@vger.kernel.org
538 mailto:git@vger.kernel.org
539Git 1.7.1 08/16/2017 GIT-PUSH(1)