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] [--follow-tags] [-n | --dry-run] [--receive-pack=<git-receive-pack>]
10 [--repo=<repository>] [-f | --force] [--prune] [-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 When the command line does not specify where to push with the
23 <repository> argument, branch.*.remote configuration for the current
24 branch is consulted to determine where to push. If the configuration is
25 missing, it defaults to origin.
26 When the command line does not specify what to push with <refspec>...
28 arguments or --all, --mirror, --tags options, the command finds the
29 default <refspec> by consulting remote.*.push configuration, and if it
30 is not found, honors push.default configuration to decide what to push
31 (See gitlink:git-config[1] for the meaning of push.default).
32
34 <repository>
35 The "remote" repository that is destination of a push operation.
36 This parameter can be either a URL (see the section GIT URLS below)
37 or the name of a remote (see the section REMOTES below).
38 <refspec>...
40 Specify what destination ref to update with what source object. The
41 format of a <refspec> parameter is an optional plus +, followed by
42 the source object <src>, followed by a colon :, followed by the
43 destination ref <dst>.
44 The <src> is often the name of the branch you would want to push,
46 but it can be any arbitrary "SHA-1 expression", such as master~4 or
47 HEAD (see gitrevisions(7)).
48 The <dst> tells which ref on the remote side is updated with this
50 push. Arbitrary expressions cannot be used here, an actual ref must
51 be named. If :<dst> is omitted, the same ref as <src> will be
52 updated.
53 The object referenced by <src> is used to update the <dst>
55 reference on the remote side. By default this is only allowed if
56 <dst> is not a tag (annotated or lightweight), and then only if it
57 can fast-forward <dst>. By having the optional leading +, you can
58 tell Git to update the <dst> ref even if it is not allowed by
59 default (e.g., it is not a fast-forward.) This does not attempt to
60 merge <src> into <dst>. See EXAMPLES below for details.
61 tag <tag> means the same as refs/tags/<tag>:refs/tags/<tag>.
63 Pushing an empty <src> allows you to delete the <dst> ref from the
65 remote repository.
66 The special refspec : (or +: to allow non-fast-forward updates)
68 directs Git to push "matching" branches: for every branch that
69 exists on the local side, the remote side is updated if a branch of
70 the same name already exists on the remote side.
71 --all
73 Instead of naming each ref to push, specifies that all refs under
74 refs/heads/ be pushed.
75 --prune
77 Remove remote branches that don’t have a local counterpart. For
78 example a remote branch tmp will be removed if a local branch with
79 the same name doesn’t exist any more. This also respects refspecs,
80 e.g. git push --prune remote refs/heads/*:refs/tmp/* would make
81 sure that remote refs/tmp/foo will be removed if refs/heads/foo
82 doesn’t exist.
83 --mirror
85 Instead of naming each ref to push, specifies that all refs under
86 refs/ (which includes but is not limited to refs/heads/,
87 refs/remotes/, and refs/tags/) be mirrored to the remote
88 repository. Newly created local refs will be pushed to the remote
89 end, locally updated refs will be force updated on the remote end,
90 and deleted refs will be removed from the remote end. This is the
91 default if the configuration option remote.<remote>.mirror is set.
92 -n, --dry-run
94 Do everything except actually send the updates.
95 --porcelain
97 Produce machine-readable output. The output status line for each
98 ref will be tab-separated and sent to stdout instead of stderr. The
99 full symbolic names of the refs will be given.
100 --delete
102 All listed refs are deleted from the remote repository. This is the
103 same as prefixing all refs with a colon.
104 --tags
106 All refs under refs/tags are pushed, in addition to refspecs
107 explicitly listed on the command line.
108 --follow-tags
110 Push all the refs that would be pushed without this option, and
111 also push annotated tags in refs/tags that are missing from the
112 remote but are pointing at committish that are reachable from the
113 refs being pushed.
114 --receive-pack=<git-receive-pack>, --exec=<git-receive-pack>
116 Path to the git-receive-pack program on the remote end. Sometimes
117 useful when pushing to a remote repository over ssh, and you do not
118 have the program in a directory on the default $PATH.
119 -f, --force
121 Usually, the command refuses to update a remote ref that is not an
122 ancestor of the local ref used to overwrite it. This flag disables
123 the check. This can cause the remote repository to lose commits;
124 use it with care.
125 --repo=<repository>
127 This option is only relevant if no <repository> argument is passed
128 in the invocation. In this case, git push derives the remote name
129 from the current branch: If it tracks a remote branch, then that
130 remote repository is pushed to. Otherwise, the name "origin" is
131 used. For this latter case, this option can be used to override the
132 name "origin". In other words, the difference between these two
133 commands
134 git push public #1
136 git push --repo=public #2
137 is that #1 always pushes to "public" whereas #2 pushes to "public"
139 only if the current branch does not track a remote branch. This is
140 useful if you write an alias or script around git push.
141 -u, --set-upstream
143 For every branch that is up to date or successfully pushed, add
144 upstream (tracking) reference, used by argument-less git-pull(1)
145 and other commands. For more information, see branch.<name>.merge
146 in git-config(1).
147 --[no-]thin
149 These options are passed to git-send-pack(1). A thin transfer
150 significantly reduces the amount of sent data when the sender and
151 receiver share many of the same objects in common. The default is
152 --thin.
153 -q, --quiet
155 Suppress all output, including the listing of updated refs, unless
156 an error occurs. Progress is not reported to the standard error
157 stream.
158 -v, --verbose
160 Run verbosely.
161 --progress
163 Progress status is reported on the standard error stream by default
164 when it is attached to a terminal, unless -q is specified. This
165 flag forces progress status even if the standard error stream is
166 not directed to a terminal.
167 --recurse-submodules=check|on-demand
169 Make sure all submodule commits used by the revisions to be pushed
170 are available on a remote-tracking branch. If check is used Git
171 will verify that all submodule commits that changed in the
172 revisions to be pushed are available on at least one remote of the
173 submodule. If any commits are missing the push will be aborted and
174 exit with non-zero status. If on-demand is used all submodules that
175 changed in the revisions to be pushed will be pushed. If on-demand
176 was not able to push all necessary revisions it will also be
177 aborted and exit with non-zero status.
178
180 In general, URLs contain information about the transport protocol, the
181 address of the remote server, and the path to the repository. Depending
182 on the transport protocol, some of this information may be absent.
183 Git supports ssh, git, http, and https protocols (in addition, ftp, and
185 ftps can be used for fetching and rsync can be used for fetching and
186 pushing, but these are inefficient and deprecated; do not use them).
187 The following syntaxes may be used with them:
189 · ssh://[user@]host.xz[:port]/path/to/repo.git/
191 · git://host.xz[:port]/path/to/repo.git/
193 · http[s]://host.xz[:port]/path/to/repo.git/
195 · ftp[s]://host.xz[:port]/path/to/repo.git/
197 · rsync://host.xz/path/to/repo.git/
199 An alternative scp-like syntax may also be used with the ssh protocol:
201 · [user@]host.xz:path/to/repo.git/
203 The ssh and git protocols additionally support ~username expansion:
205 · ssh://[user@]host.xz[:port]/~[user]/path/to/repo.git/
207 · git://host.xz[:port]/~[user]/path/to/repo.git/
209 · [user@]host.xz:/~[user]/path/to/repo.git/
211 For local repositories, also supported by Git natively, the following
213 syntaxes may be used:
214 · /path/to/repo.git/
216 · file:///path/to/repo.git/
218 These two syntaxes are mostly equivalent, except when cloning, when the
220 former implies --local option. See git-clone(1) for details.
221 When Git doesn’t know how to handle a certain transport protocol, it
223 attempts to use the remote-<transport> remote helper, if one exists. To
224 explicitly request a remote helper, the following syntax may be used:
225 · <transport>::<address>
227 where <address> may be a path, a server and path, or an arbitrary
229 URL-like string recognized by the specific remote helper being invoked.
230 See gitremote-helpers(1) for details.
231 If there are a large number of similarly-named remote repositories and
233 you want to use a different format for them (such that the URLs you use
234 will be rewritten into URLs that work), you can create a configuration
235 section of the form:
236 [url "<actual url base>"]
238 insteadOf = <other url base>
239 For example, with this:
242 [url "git://git.host.xz/"]
244 insteadOf = host.xz:/path/to/
245 insteadOf = work:
246 a URL like "work:repo.git" or like "host.xz:/path/to/repo.git" will be
249 rewritten in any context that takes a URL to be
250 "git://git.host.xz/repo.git".
251 If you want to rewrite URLs for push only, you can create a
253 configuration section of the form:
254 [url "<actual url base>"]
256 pushInsteadOf = <other url base>
257 For example, with this:
260 [url "ssh://example.org/"]
262 pushInsteadOf = git://example.org/
263 a URL like "git://example.org/path/to/repo.git" will be rewritten to
266 "ssh://example.org/path/to/repo.git" for pushes, but pulls will still
267 use the original URL.
268
270 The name of one of the following can be used instead of a URL as
271 <repository> argument:
272 · a remote in the Git configuration file: $GIT_DIR/config,
274 · a file in the $GIT_DIR/remotes directory, or
276 · a file in the $GIT_DIR/branches directory.
278 All of these also allow you to omit the refspec from the command line
280 because they each contain a refspec which git will use by default.
281 Named remote in configuration file
283 You can choose to provide the name of a remote which you had previously
284 configured using git-remote(1), git-config(1) or even by a manual edit
285 to the $GIT_DIR/config file. The URL of this remote will be used to
286 access the repository. The refspec of this remote will be used by
287 default when you do not provide a refspec on the command line. The
288 entry in the config file would appear like this:
289 [remote "<name>"]
291 url = <url>
292 pushurl = <pushurl>
293 push = <refspec>
294 fetch = <refspec>
295 The <pushurl> is used for pushes only. It is optional and defaults to
298 <url>.
299 Named file in $GIT_DIR/remotes
301 You can choose to provide the name of a file in $GIT_DIR/remotes. The
302 URL in this file will be used to access the repository. The refspec in
303 this file will be used as default when you do not provide a refspec on
304 the command line. This file should have the following format:
305 URL: one of the above URL format
307 Push: <refspec>
308 Pull: <refspec>
309 Push: lines are used by git push and Pull: lines are used by git pull
312 and git fetch. Multiple Push: and Pull: lines may be specified for
313 additional branch mappings.
314 Named file in $GIT_DIR/branches
316 You can choose to provide the name of a file in $GIT_DIR/branches. The
317 URL in this file will be used to access the repository. This file
318 should have the following format:
319 <url>#<head>
321 <url> is required; #<head> is optional.
324 Depending on the operation, git will use one of the following refspecs,
326 if you don’t provide one on the command line. <branch> is the name of
327 this file in $GIT_DIR/branches and <head> defaults to master.
328 git fetch uses:
330 refs/heads/<head>:refs/heads/<branch>
332 git push uses:
335 HEAD:refs/heads/<head>
337
340 The output of "git push" depends on the transport method used; this
341 section describes the output when pushing over the Git protocol (either
342 locally or via ssh).
343 The status of the push is output in tabular form, with each line
345 representing the status of a single ref. Each line is of the form:
346 <flag> <summary> <from> -> <to> (<reason>)
348 If --porcelain is used, then each line of the output is of the form:
351 <flag> \t <from>:<to> \t <summary> (<reason>)
353 The status of up-to-date refs is shown only if --porcelain or --verbose
356 option is used.
357 flag
359 A single character indicating the status of the ref:
360 (space)
362 for a successfully pushed fast-forward;
363 +
365 for a successful forced update;
366 -
368 for a successfully deleted ref;
369 *
371 for a successfully pushed new ref;
372 !
374 for a ref that was rejected or failed to push; and
375 =
377 for a ref that was up to date and did not need pushing.
378 summary
380 For a successfully pushed ref, the summary shows the old and new
381 values of the ref in a form suitable for using as an argument to
382 git log (this is <old>..<new> in most cases, and <old>...<new> for
383 forced non-fast-forward updates).
384 For a failed update, more details are given:
386 rejected
388 Git did not try to send the ref at all, typically because it is
389 not a fast-forward and you did not force the update.
390 remote rejected
392 The remote end refused the update. Usually caused by a hook on
393 the remote side, or because the remote repository has one of
394 the following safety options in effect:
395 receive.denyCurrentBranch (for pushes to the checked out
396 branch), receive.denyNonFastForwards (for forced
397 non-fast-forward updates), receive.denyDeletes or
398 receive.denyDeleteCurrent. See git-config(1).
399 remote failure
401 The remote end did not report the successful update of the ref,
402 perhaps because of a temporary error on the remote side, a
403 break in the network connection, or other transient error.
404 from
406 The name of the local ref being pushed, minus its refs/<type>/
407 prefix. In the case of deletion, the name of the local ref is
408 omitted.
409 to
411 The name of the remote ref being updated, minus its refs/<type>/
412 prefix.
413 reason
415 A human-readable explanation. In the case of successfully pushed
416 refs, no explanation is needed. For a failed ref, the reason for
417 failure is described.
418
420 When an update changes a branch (or more in general, a ref) that used
421 to point at commit A to point at another commit B, it is called a
422 fast-forward update if and only if B is a descendant of A.
423 In a fast-forward update from A to B, the set of commits that the
425 original commit A built on top of is a subset of the commits the new
426 commit B builds on top of. Hence, it does not lose any history.
427 In contrast, a non-fast-forward update will lose history. For example,
429 suppose you and somebody else started at the same commit X, and you
430 built a history leading to commit B while the other person built a
431 history leading to commit A. The history looks like this:
432 B
434 /
435 ---X---A
436 Further suppose that the other person already pushed changes leading to
439 A back to the original repository from which you two obtained the
440 original commit X.
441 The push done by the other person updated the branch that used to point
443 at commit X to point at commit A. It is a fast-forward.
444 But if you try to push, you will attempt to update the branch (that now
446 points at A) with commit B. This does not fast-forward. If you did so,
447 the changes introduced by commit A will be lost, because everybody will
448 now start building on top of B.
449 The command by default does not allow an update that is not a
451 fast-forward to prevent such loss of history.
452 If you do not want to lose your work (history from X to B) nor the work
454 by the other person (history from X to A), you would need to first
455 fetch the history from the repository, create a history that contains
456 changes done by both parties, and push the result back.
457 You can perform "git pull", resolve potential conflicts, and "git push"
459 the result. A "git pull" will create a merge commit C between commits A
460 and B.
461 B---C
463 / /
464 ---X---A
465 Updating A with the resulting merge commit will fast-forward and your
468 push will be accepted.
469 Alternatively, you can rebase your change between X and B on top of A,
471 with "git pull --rebase", and push the result back. The rebase will
472 create a new commit D that builds the change between X and B on top of
473 A.
474 B D
476 / /
477 ---X---A
478 Again, updating A with this commit will fast-forward and your push will
481 be accepted.
482 There is another common situation where you may encounter
484 non-fast-forward rejection when you try to push, and it is possible
485 even when you are pushing into a repository nobody else pushes into.
486 After you push commit A yourself (in the first picture in this
487 section), replace it with "git commit --amend" to produce commit B, and
488 you try to push it out, because forgot that you have pushed A out
489 already. In such a case, and only if you are certain that nobody in the
490 meantime fetched your earlier commit A (and started building on top of
491 it), you can run "git push --force" to overwrite it. In other words,
492 "git push --force" is a method reserved for a case where you do mean to
493 lose history.
494
496 git push
497 Works like git push <remote>, where <remote> is the current
498 branch’s remote (or origin, if no remote is configured for the
499 current branch).
500 git push origin
502 Without additional configuration, works like git push origin :.
503 The default behavior of this command when no <refspec> is given can
505 be configured by setting the push option of the remote, or the
506 push.default configuration variable.
507 For example, to default to pushing only the current branch to
509 origin use git config remote.origin.push HEAD. Any valid <refspec>
510 (like the ones in the examples below) can be configured as the
511 default for git push origin.
512 git push origin :
514 Push "matching" branches to origin. See <refspec> in the OPTIONS
515 section above for a description of "matching" branches.
516 git push origin master
518 Find a ref that matches master in the source repository (most
519 likely, it would find refs/heads/master), and update the same ref
520 (e.g. refs/heads/master) in origin repository with it. If master
521 did not exist remotely, it would be created.
522 git push origin HEAD
524 A handy way to push the current branch to the same name on the
525 remote.
526 git push mothership master:satellite/master dev:satellite/dev
528 Use the source ref that matches master (e.g. refs/heads/master) to
529 update the ref that matches satellite/master (most probably
530 refs/remotes/satellite/master) in the mothership repository; do the
531 same for dev and satellite/dev.
532 This is to emulate git fetch run on the mothership using git push
534 that is run in the opposite direction in order to integrate the
535 work done on satellite, and is often necessary when you can only
536 make connection in one way (i.e. satellite can ssh into mothership
537 but mothership cannot initiate connection to satellite because the
538 latter is behind a firewall or does not run sshd).
539 After running this git push on the satellite machine, you would ssh
541 into the mothership and run git merge there to complete the
542 emulation of git pull that were run on mothership to pull changes
543 made on satellite.
544 git push origin HEAD:master
546 Push the current branch to the remote ref matching master in the
547 origin repository. This form is convenient to push the current
548 branch without thinking about its local name.
549 git push origin master:refs/heads/experimental
551 Create the branch experimental in the origin repository by copying
552 the current master branch. This form is only needed to create a new
553 branch or tag in the remote repository when the local name and the
554 remote name are different; otherwise, the ref name on its own will
555 work.
556 git push origin :experimental
558 Find a ref that matches experimental in the origin repository (e.g.
559 refs/heads/experimental), and delete it.
560 git push origin +dev:master
562 Update the origin repository’s master branch with the dev branch,
563 allowing non-fast-forward updates. This can leave unreferenced
564 commits dangling in the origin repository. Consider the following
565 situation, where a fast-forward is not possible:
566 o---o---o---A---B origin/master
568 \
569 X---Y---Z dev
570 The above command would change the origin repository to
572 A---B (unnamed branch)
574 /
575 o---o---o---X---Y---Z master
576 Commits A and B would no longer belong to a branch with a symbolic
578 name, and so would be unreachable. As such, these commits would be
579 removed by a git gc command on the origin repository.
580
582 Part of the git(1) suite
583Git 1.8.3.1 11/19/2018 GIT-PUSH(1)