1git-push(1) 2=========== 3 4NAME 5---- 6git-push - Update remote refs along with associated objects 7 8 9SYNOPSIS 10-------- 11[verse] 12'git push' [--all | --mirror | --tags] [-n | --dry-run] [--receive-pack=<git-receive-pack>] 13 [--repo=<repository>] [-f | --force] [-v | --verbose] [-u | --set-upstream] 14 [<repository> [<refspec>...]] 15 16DESCRIPTION 17----------- 18 19Updates remote refs using local refs, while sending objects 20necessary to complete the given refs. 21 22You can make interesting things happen to a repository 23every time you push into it, by setting up 'hooks' there. See 24documentation for linkgit:git-receive-pack[1]. 25 26 27OPTIONS[[OPTIONS]] 28------------------ 29<repository>:: 30 The "remote" repository that is destination of a push 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). 34 35<refspec>...:: 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. 41+ 42The <src> is often the name of the branch you would want to push, but 43it can be any arbitrary "SHA-1 expression", such as `master~4` or 44`HEAD` (see linkgit:gitrevisions[7]). 45+ 46The <dst> tells which ref on the remote side is updated with this 47push. Arbitrary expressions cannot be used here, an actual ref must 48be named. If `:`<dst> is omitted, the same ref as <src> will be 49updated. 50+ 51The object referenced by <src> is used to update the <dst> reference 52on the remote side, but by default this is only allowed if the 53update can fast-forward <dst>. By having the optional leading `{plus}`, 54you can tell git to update the <dst> ref even when the update is not a 55fast-forward. This does *not* attempt to merge <src> into <dst>. See 56EXAMPLES below for details. 57+ 58`tag <tag>` means the same as `refs/tags/<tag>:refs/tags/<tag>`. 59+ 60Pushing an empty <src> allows you to delete the <dst> ref from 61the remote repository. 62+ 63The special refspec `:` (or `{plus}:` to allow non-fast-forward updates) 64directs git to push "matching" branches: for every branch that exists on 65the local side, the remote side is updated if a branch of the same name 66already exists on the remote side. This is the default operation mode 67if no explicit refspec is found (that is neither on the command line 68nor in any Push line of the corresponding remotes file---see below). 69 70--all:: 71 Instead of naming each ref to push, specifies that all 72 refs under `refs/heads/` be pushed. 73 74--mirror:: 75 Instead of naming each ref to push, specifies that all 76 refs under `refs/` (which includes but is not 77 limited to `refs/heads/`, `refs/remotes/`, and `refs/tags/`) 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 81 will be removed from the remote end. This is the default 82 if the configuration option `remote.<remote>.mirror` is 83 set. 84 85-n:: 86--dry-run:: 87 Do everything except actually send the updates. 88 89--porcelain:: 90 Produce machine-readable output. The output status line for each ref 91 will be tab-separated and sent to stdout instead of stderr. The full 92 symbolic names of the refs will be given. 93 94--delete:: 95 All listed refs are deleted from the remote repository. This is 96 the same as prefixing all refs with a colon. 97 98--tags:: 99 All refs under `refs/tags` are pushed, in 100 addition to refspecs explicitly listed on the command 101 line. 102 103--receive-pack=<git-receive-pack>:: 104--exec=<git-receive-pack>:: 105 Path to the 'git-receive-pack' program on the remote 106 end. Sometimes useful when pushing to a remote 107 repository over ssh, and you do not have the program in 108 a directory on the default $PATH. 109 110-f:: 111--force:: 112 Usually, the command refuses to update a remote ref that is 113 not an ancestor of the local ref used to overwrite it. 114 This flag disables the check. This can cause the 115 remote repository to lose commits; use it with care. 116 117--repo=<repository>:: 118 This option is only relevant if no <repository> argument is 119 passed in the invocation. In this case, 'git push' derives the 120 remote name from the current branch: If it tracks a remote 121 branch, then that remote repository is pushed to. Otherwise, 122 the name "origin" is used. For this latter case, this option 123 can be used to override the name "origin". In other words, 124 the difference between these two commands 125+ 126-------------------------- 127git push public #1 128git push --repo=public #2 129-------------------------- 130+ 131is that #1 always pushes to "public" whereas #2 pushes to "public" 132only if the current branch does not track a remote branch. This is 133useful if you write an alias or script around 'git push'. 134 135-u:: 136--set-upstream:: 137 For every branch that is up to date or successfully pushed, add 138 upstream (tracking) reference, used by argument-less 139 linkgit:git-pull[1] and other commands. For more information, 140 see 'branch.<name>.merge' in linkgit:git-config[1]. 141 142--thin:: 143--no-thin:: 144 These options are passed to linkgit:git-send-pack[1]. A thin transfer 145 significantly reduces the amount of sent data when the sender and 146 receiver share many of the same objects in common. The default is 147 \--thin. 148 149-q:: 150--quiet:: 151 Suppress all output, including the listing of updated refs, 152 unless an error occurs. Progress is not reported to the standard 153 error stream. 154 155-v:: 156--verbose:: 157 Run verbosely. 158 159--progress:: 160 Progress status is reported on the standard error stream 161 by default when it is attached to a terminal, unless -q 162 is specified. This flag forces progress status even if the 163 standard error stream is not directed to a terminal. 164 165include::urls-remotes.txt[] 166 167OUTPUT 168------ 169 170The output of "git push" depends on the transport method used; this 171section describes the output when pushing over the git protocol (either 172locally or via ssh). 173 174The status of the push is output in tabular form, with each line 175representing the status of a single ref. Each line is of the form: 176 177------------------------------- 178 <flag> <summary> <from> -> <to> (<reason>) 179------------------------------- 180 181If --porcelain is used, then each line of the output is of the form: 182 183------------------------------- 184 <flag> \t <from>:<to> \t <summary> (<reason>) 185------------------------------- 186 187The status of up-to-date refs is shown only if --porcelain or --verbose 188option is used. 189 190flag:: 191 A single character indicating the status of the ref: 192(space);; for a successfully pushed fast-forward; 193`{plus}`;; for a successful forced update; 194`-`;; for a successfully deleted ref; 195`*`;; for a successfully pushed new ref; 196`!`;; for a ref that was rejected or failed to push; and 197`=`;; for a ref that was up to date and did not need pushing. 198 199summary:: 200 For a successfully pushed ref, the summary shows the old and new 201 values of the ref in a form suitable for using as an argument to 202 `git log` (this is `<old>..<new>` in most cases, and 203 `<old>\...<new>` for forced non-fast-forward updates). 204+ 205For a failed update, more details are given: 206+ 207-- 208rejected:: 209 Git did not try to send the ref at all, typically because it 210 is not a fast-forward and you did not force the update. 211 212remote rejected:: 213 The remote end refused the update. Usually caused by a hook 214 on the remote side, or because the remote repository has one 215 of the following safety options in effect: 216 `receive.denyCurrentBranch` (for pushes to the checked out 217 branch), `receive.denyNonFastForwards` (for forced 218 non-fast-forward updates), `receive.denyDeletes` or 219 `receive.denyDeleteCurrent`. See linkgit:git-config[1]. 220 221remote failure:: 222 The remote end did not report the successful update of the ref, 223 perhaps because of a temporary error on the remote side, a 224 break in the network connection, or other transient error. 225-- 226 227from:: 228 The name of the local ref being pushed, minus its 229 `refs/<type>/` prefix. In the case of deletion, the 230 name of the local ref is omitted. 231 232to:: 233 The name of the remote ref being updated, minus its 234 `refs/<type>/` prefix. 235 236reason:: 237 A human-readable explanation. In the case of successfully pushed 238 refs, no explanation is needed. For a failed ref, the reason for 239 failure is described. 240 241Note about fast-forwards 242------------------------ 243 244When an update changes a branch (or more in general, a ref) that used to 245point at commit A to point at another commit B, it is called a 246fast-forward update if and only if B is a descendant of A. 247 248In a fast-forward update from A to B, the set of commits that the original 249commit A built on top of is a subset of the commits the new commit B 250builds on top of. Hence, it does not lose any history. 251 252In contrast, a non-fast-forward update will lose history. For example, 253suppose you and somebody else started at the same commit X, and you built 254a history leading to commit B while the other person built a history 255leading to commit A. The history looks like this: 256 257---------------- 258 259 B 260 / 261 ---X---A 262 263---------------- 264 265Further suppose that the other person already pushed changes leading to A 266back to the original repository you two obtained the original commit X. 267 268The push done by the other person updated the branch that used to point at 269commit X to point at commit A. It is a fast-forward. 270 271But if you try to push, you will attempt to update the branch (that 272now points at A) with commit B. This does _not_ fast-forward. If you did 273so, the changes introduced by commit A will be lost, because everybody 274will now start building on top of B. 275 276The command by default does not allow an update that is not a fast-forward 277to prevent such loss of history. 278 279If you do not want to lose your work (history from X to B) nor the work by 280the other person (history from X to A), you would need to first fetch the 281history from the repository, create a history that contains changes done 282by both parties, and push the result back. 283 284You can perform "git pull", resolve potential conflicts, and "git push" 285the result. A "git pull" will create a merge commit C between commits A 286and B. 287 288---------------- 289 290 B---C 291 / / 292 ---X---A 293 294---------------- 295 296Updating A with the resulting merge commit will fast-forward and your 297push will be accepted. 298 299Alternatively, you can rebase your change between X and B on top of A, 300with "git pull --rebase", and push the result back. The rebase will 301create a new commit D that builds the change between X and B on top of 302A. 303 304---------------- 305 306 B D 307 / / 308 ---X---A 309 310---------------- 311 312Again, updating A with this commit will fast-forward and your push will be 313accepted. 314 315There is another common situation where you may encounter non-fast-forward 316rejection when you try to push, and it is possible even when you are 317pushing into a repository nobody else pushes into. After you push commit 318A yourself (in the first picture in this section), replace it with "git 319commit --amend" to produce commit B, and you try to push it out, because 320forgot that you have pushed A out already. In such a case, and only if 321you are certain that nobody in the meantime fetched your earlier commit A 322(and started building on top of it), you can run "git push --force" to 323overwrite it. In other words, "git push --force" is a method reserved for 324a case where you do mean to lose history. 325 326 327Examples 328-------- 329 330git push:: 331 Works like `git push <remote>`, where <remote> is the 332 current branch's remote (or `origin`, if no remote is 333 configured for the current branch). 334 335git push origin:: 336 Without additional configuration, works like 337 `git push origin :`. 338+ 339The default behavior of this command when no <refspec> is given can be 340configured by setting the `push` option of the remote. 341+ 342For example, to default to pushing only the current branch to `origin` 343use `git config remote.origin.push HEAD`. Any valid <refspec> (like 344the ones in the examples below) can be configured as the default for 345`git push origin`. 346 347git push origin ::: 348 Push "matching" branches to `origin`. See 349 <refspec> in the <<OPTIONS,OPTIONS>> section above for a 350 description of "matching" branches. 351 352git push origin master:: 353 Find a ref that matches `master` in the source repository 354 (most likely, it would find `refs/heads/master`), and update 355 the same ref (e.g. `refs/heads/master`) in `origin` repository 356 with it. If `master` did not exist remotely, it would be 357 created. 358 359git push origin HEAD:: 360 A handy way to push the current branch to the same name on the 361 remote. 362 363git push origin master:satellite/master dev:satellite/dev:: 364 Use the source ref that matches `master` (e.g. `refs/heads/master`) 365 to update the ref that matches `satellite/master` (most probably 366 `refs/remotes/satellite/master`) in the `origin` repository, then 367 do the same for `dev` and `satellite/dev`. 368 369git push origin HEAD:master:: 370 Push the current branch to the remote ref matching `master` in the 371 `origin` repository. This form is convenient to push the current 372 branch without thinking about its local name. 373 374git push origin master:refs/heads/experimental:: 375 Create the branch `experimental` in the `origin` repository 376 by copying the current `master` branch. This form is only 377 needed to create a new branch or tag in the remote repository when 378 the local name and the remote name are different; otherwise, 379 the ref name on its own will work. 380 381git push origin :experimental:: 382 Find a ref that matches `experimental` in the `origin` repository 383 (e.g. `refs/heads/experimental`), and delete it. 384 385git push origin {plus}dev:master:: 386 Update the origin repository's master branch with the dev branch, 387 allowing non-fast-forward updates. *This can leave unreferenced 388 commits dangling in the origin repository.* Consider the 389 following situation, where a fast-forward is not possible: 390+ 391---- 392 o---o---o---A---B origin/master 393 \ 394 X---Y---Z dev 395---- 396+ 397The above command would change the origin repository to 398+ 399---- 400 A---B (unnamed branch) 401 / 402 o---o---o---X---Y---Z master 403---- 404+ 405Commits A and B would no longer belong to a branch with a symbolic name, 406and so would be unreachable. As such, these commits would be removed by 407a `git gc` command on the origin repository. 408 409GIT 410--- 411Part of the linkgit:git[1] suite