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 165--recurse-submodules=check|on-demand:: 166 Make sure all submodule commits used by the revisions to be 167 pushed are available on a remote tracking branch. If 'check' is 168 used git will verify that all submodule commits that changed in 169 the revisions to be pushed are available on at least one remote 170 of the submodule. If any commits are missing the push will be 171 aborted and exit with non-zero status. If 'on-demand' is used 172 all submodules that changed in the revisions to be pushed will 173 be pushed. If on-demand was not able to push all necessary 174 revisions it will also be aborted and exit with non-zero status. 175 176 177include::urls-remotes.txt[] 178 179OUTPUT 180------ 181 182The output of "git push" depends on the transport method used; this 183section describes the output when pushing over the git protocol (either 184locally or via ssh). 185 186The status of the push is output in tabular form, with each line 187representing the status of a single ref. Each line is of the form: 188 189------------------------------- 190 <flag> <summary> <from> -> <to> (<reason>) 191------------------------------- 192 193If --porcelain is used, then each line of the output is of the form: 194 195------------------------------- 196 <flag> \t <from>:<to> \t <summary> (<reason>) 197------------------------------- 198 199The status of up-to-date refs is shown only if --porcelain or --verbose 200option is used. 201 202flag:: 203 A single character indicating the status of the ref: 204(space);; for a successfully pushed fast-forward; 205`{plus}`;; for a successful forced update; 206`-`;; for a successfully deleted ref; 207`*`;; for a successfully pushed new ref; 208`!`;; for a ref that was rejected or failed to push; and 209`=`;; for a ref that was up to date and did not need pushing. 210 211summary:: 212 For a successfully pushed ref, the summary shows the old and new 213 values of the ref in a form suitable for using as an argument to 214 `git log` (this is `<old>..<new>` in most cases, and 215 `<old>\...<new>` for forced non-fast-forward updates). 216+ 217For a failed update, more details are given: 218+ 219-- 220rejected:: 221 Git did not try to send the ref at all, typically because it 222 is not a fast-forward and you did not force the update. 223 224remote rejected:: 225 The remote end refused the update. Usually caused by a hook 226 on the remote side, or because the remote repository has one 227 of the following safety options in effect: 228 `receive.denyCurrentBranch` (for pushes to the checked out 229 branch), `receive.denyNonFastForwards` (for forced 230 non-fast-forward updates), `receive.denyDeletes` or 231 `receive.denyDeleteCurrent`. See linkgit:git-config[1]. 232 233remote failure:: 234 The remote end did not report the successful update of the ref, 235 perhaps because of a temporary error on the remote side, a 236 break in the network connection, or other transient error. 237-- 238 239from:: 240 The name of the local ref being pushed, minus its 241 `refs/<type>/` prefix. In the case of deletion, the 242 name of the local ref is omitted. 243 244to:: 245 The name of the remote ref being updated, minus its 246 `refs/<type>/` prefix. 247 248reason:: 249 A human-readable explanation. In the case of successfully pushed 250 refs, no explanation is needed. For a failed ref, the reason for 251 failure is described. 252 253Note about fast-forwards 254------------------------ 255 256When an update changes a branch (or more in general, a ref) that used to 257point at commit A to point at another commit B, it is called a 258fast-forward update if and only if B is a descendant of A. 259 260In a fast-forward update from A to B, the set of commits that the original 261commit A built on top of is a subset of the commits the new commit B 262builds on top of. Hence, it does not lose any history. 263 264In contrast, a non-fast-forward update will lose history. For example, 265suppose you and somebody else started at the same commit X, and you built 266a history leading to commit B while the other person built a history 267leading to commit A. The history looks like this: 268 269---------------- 270 271 B 272 / 273 ---X---A 274 275---------------- 276 277Further suppose that the other person already pushed changes leading to A 278back to the original repository you two obtained the original commit X. 279 280The push done by the other person updated the branch that used to point at 281commit X to point at commit A. It is a fast-forward. 282 283But if you try to push, you will attempt to update the branch (that 284now points at A) with commit B. This does _not_ fast-forward. If you did 285so, the changes introduced by commit A will be lost, because everybody 286will now start building on top of B. 287 288The command by default does not allow an update that is not a fast-forward 289to prevent such loss of history. 290 291If you do not want to lose your work (history from X to B) nor the work by 292the other person (history from X to A), you would need to first fetch the 293history from the repository, create a history that contains changes done 294by both parties, and push the result back. 295 296You can perform "git pull", resolve potential conflicts, and "git push" 297the result. A "git pull" will create a merge commit C between commits A 298and B. 299 300---------------- 301 302 B---C 303 / / 304 ---X---A 305 306---------------- 307 308Updating A with the resulting merge commit will fast-forward and your 309push will be accepted. 310 311Alternatively, you can rebase your change between X and B on top of A, 312with "git pull --rebase", and push the result back. The rebase will 313create a new commit D that builds the change between X and B on top of 314A. 315 316---------------- 317 318 B D 319 / / 320 ---X---A 321 322---------------- 323 324Again, updating A with this commit will fast-forward and your push will be 325accepted. 326 327There is another common situation where you may encounter non-fast-forward 328rejection when you try to push, and it is possible even when you are 329pushing into a repository nobody else pushes into. After you push commit 330A yourself (in the first picture in this section), replace it with "git 331commit --amend" to produce commit B, and you try to push it out, because 332forgot that you have pushed A out already. In such a case, and only if 333you are certain that nobody in the meantime fetched your earlier commit A 334(and started building on top of it), you can run "git push --force" to 335overwrite it. In other words, "git push --force" is a method reserved for 336a case where you do mean to lose history. 337 338 339Examples 340-------- 341 342`git push`:: 343 Works like `git push <remote>`, where <remote> is the 344 current branch's remote (or `origin`, if no remote is 345 configured for the current branch). 346 347`git push origin`:: 348 Without additional configuration, works like 349 `git push origin :`. 350+ 351The default behavior of this command when no <refspec> is given can be 352configured by setting the `push` option of the remote. 353+ 354For example, to default to pushing only the current branch to `origin` 355use `git config remote.origin.push HEAD`. Any valid <refspec> (like 356the ones in the examples below) can be configured as the default for 357`git push origin`. 358 359`git push origin :`:: 360 Push "matching" branches to `origin`. See 361 <refspec> in the <<OPTIONS,OPTIONS>> section above for a 362 description of "matching" branches. 363 364`git push origin master`:: 365 Find a ref that matches `master` in the source repository 366 (most likely, it would find `refs/heads/master`), and update 367 the same ref (e.g. `refs/heads/master`) in `origin` repository 368 with it. If `master` did not exist remotely, it would be 369 created. 370 371`git push origin HEAD`:: 372 A handy way to push the current branch to the same name on the 373 remote. 374 375`git push origin master:satellite/master dev:satellite/dev`:: 376 Use the source ref that matches `master` (e.g. `refs/heads/master`) 377 to update the ref that matches `satellite/master` (most probably 378 `refs/remotes/satellite/master`) in the `origin` repository, then 379 do the same for `dev` and `satellite/dev`. 380 381`git push origin HEAD:master`:: 382 Push the current branch to the remote ref matching `master` in the 383 `origin` repository. This form is convenient to push the current 384 branch without thinking about its local name. 385 386`git push origin master:refs/heads/experimental`:: 387 Create the branch `experimental` in the `origin` repository 388 by copying the current `master` branch. This form is only 389 needed to create a new branch or tag in the remote repository when 390 the local name and the remote name are different; otherwise, 391 the ref name on its own will work. 392 393`git push origin :experimental`:: 394 Find a ref that matches `experimental` in the `origin` repository 395 (e.g. `refs/heads/experimental`), and delete it. 396 397`git push origin {plus}dev:master`:: 398 Update the origin repository's master branch with the dev branch, 399 allowing non-fast-forward updates. *This can leave unreferenced 400 commits dangling in the origin repository.* Consider the 401 following situation, where a fast-forward is not possible: 402+ 403---- 404 o---o---o---A---B origin/master 405 \ 406 X---Y---Z dev 407---- 408+ 409The above command would change the origin repository to 410+ 411---- 412 A---B (unnamed branch) 413 / 414 o---o---o---X---Y---Z master 415---- 416+ 417Commits A and B would no longer belong to a branch with a symbolic name, 418and so would be unreachable. As such, these commits would be removed by 419a `git gc` command on the origin repository. 420 421GIT 422--- 423Part of the linkgit:git[1] suite