| 1 | git-push(1) |
| 2 | =========== |
| 3 | |
| 4 | NAME |
| 5 | ---- |
| 6 | git-push - Update remote refs along with associated objects |
| 7 | |
| 8 | |
| 9 | SYNOPSIS |
| 10 | -------- |
| 11 | [synopsis] |
| 12 | git push [--all | --branches | --mirror | --tags] [--follow-tags] [--atomic] [-n | --dry-run] [--receive-pack=<git-receive-pack>] |
| 13 | [--repo=<repository>] [-f | --force] [-d | --delete] [--prune] [-q | --quiet] [-v | --verbose] |
| 14 | [-u | --set-upstream] [-o <string> | --push-option=<string>] |
| 15 | [--[no-]signed | --signed=(true|false|if-asked)] |
| 16 | [--force-with-lease[=<refname>[:<expect>]] [--force-if-includes]] |
| 17 | [--no-verify] [<repository> [<refspec>...]] |
| 18 | |
| 19 | DESCRIPTION |
| 20 | ----------- |
| 21 | Updates one or more branches, tags, or other references in one or more |
| 22 | remote repositories from your local repository, and sends all necessary |
| 23 | data that isn't already on the remote. |
| 24 | |
| 25 | The simplest way to push is `git push <remote> <branch>`. |
| 26 | `git push origin main` will push the local `main` branch to the `main` |
| 27 | branch on the remote named `origin`. |
| 28 | |
| 29 | You can also push to multiple remotes at once by using a remote group. |
| 30 | A remote group is a named list of remotes configured via `remotes.<name>` |
| 31 | in your git config: |
| 32 | |
| 33 | $ git config remotes.all-remotes "origin gitlab backup" |
| 34 | |
| 35 | Then `git push all-remotes` will push to `origin`, `gitlab`, and |
| 36 | `backup` in turn, as if you had run `git push` against each one |
| 37 | individually. Each remote is pushed independently using its own |
| 38 | push mapping configuration. There is a `remotes.<group>` entry in |
| 39 | the configuration file. (See linkgit:git-config[1]). |
| 40 | |
| 41 | The `<repository>` argument defaults to the upstream for the current |
| 42 | branch, or `origin` if there's no configured upstream. |
| 43 | |
| 44 | To decide which branches, tags, or other refs to push, Git uses |
| 45 | (in order of precedence): |
| 46 | |
| 47 | 1. The `<refspec>` argument(s) (for example `main` in `git push origin main`) |
| 48 | or the `--all`, `--mirror`, or `--tags` options |
| 49 | 2. The `remote.<name>.push` configuration for the repository being pushed to |
| 50 | 3. The `push.default` configuration. The default is `push.default=simple`, |
| 51 | which will push to a branch with the same name as the current branch. |
| 52 | See the <<CONFIGURATION,CONFIGURATION>> section below for more on `push.default`. |
| 53 | |
| 54 | `git push` may fail if you haven't set an upstream for the current branch, |
| 55 | depending on what `push.default` is set to. |
| 56 | See the <<UPSTREAM-BRANCHES,UPSTREAM BRANCHES>> section below for more |
| 57 | on how to set and use upstreams. |
| 58 | |
| 59 | You can make interesting things happen to a repository |
| 60 | every time you push into it, by setting up 'hooks' there. See |
| 61 | documentation for linkgit:git-receive-pack[1]. |
| 62 | |
| 63 | [[OPTIONS]] |
| 64 | OPTIONS |
| 65 | ------- |
| 66 | _<repository>_:: |
| 67 | The "remote" repository that is the destination of a push |
| 68 | operation. This parameter can be either a URL |
| 69 | (see the section <<URLS,GIT URLS>> below), the name |
| 70 | of a remote (see the section <<REMOTES,REMOTES>> below), |
| 71 | or the name of a remote group |
| 72 | (see the section <<REMOTE-GROUPS,REMOTE GROUPS>> below). |
| 73 | |
| 74 | `<refspec>...`:: |
| 75 | Specify what destination ref to update with what source object. |
| 76 | + |
| 77 | The format for a refspec is `[+]<src>[:<dst>]`, for example `main`, |
| 78 | `main:other`, or `HEAD^:refs/heads/main`. |
| 79 | + |
| 80 | The _<src>_ is often the name of the local branch to push, but it can be |
| 81 | any arbitrary "SHA-1 expression" (see linkgit:gitrevisions[7]). |
| 82 | + |
| 83 | The _<dst>_ determines what ref to update on the remote side. It must be the |
| 84 | name of a branch, tag, or other ref, not an arbitrary expression. |
| 85 | + |
| 86 | The `+` is optional and does the same thing as `--force`. |
| 87 | + |
| 88 | You can write a refspec using the fully expanded form (for |
| 89 | example `refs/heads/main:refs/heads/main`) which specifies the exact source |
| 90 | and destination, or with a shorter form (for example `main` or |
| 91 | `main:other`). Here are the rules for how refspecs are expanded, |
| 92 | as well as various other special refspec forms: |
| 93 | + |
| 94 | * _<src>_ without a `:<dst>` means to update the same ref as the |
| 95 | _<src>_, unless the `remote.<repository>.push` configuration specifies a |
| 96 | different _<dst>_. For example, if `main` is a branch, then the refspec |
| 97 | `main` expands to `main:refs/heads/main`. |
| 98 | * If _<dst>_ unambiguously refers to a ref on the <repository> remote, |
| 99 | then expand it to that ref. For example, if `v1.0` is a tag on the |
| 100 | remote, then `HEAD:v1.0` expands to `HEAD:refs/tags/v1.0`. |
| 101 | * If _<src>_ resolves to a ref starting with `refs/heads/` or `refs/tags/`, |
| 102 | then prepend that to <dst>. For example, if `main` is a branch, then |
| 103 | `main:other` expands to `main:refs/heads/other` |
| 104 | * The special refspec `:` (or `+:` to allow non-fast-forward updates) |
| 105 | directs Git to push "matching" branches: for every branch that exists on |
| 106 | the local side, the remote side is updated if a branch of the same name |
| 107 | already exists on the remote side. |
| 108 | * _<src>_ may contain a `*` to indicate a simple pattern match. |
| 109 | This works like a glob that matches any ref matching the pattern. |
| 110 | There must be only one `*` in both the `<src>` and `<dst>`. |
| 111 | It will map refs to the destination by replacing the * with the |
| 112 | contents matched from the source. For example, `refs/heads/*:refs/heads/*` |
| 113 | will push all branches. |
| 114 | * A refspec starting with `^` is a negative refspec. |
| 115 | This specifies refs to exclude. A ref will be considered to |
| 116 | match if it matches at least one positive refspec, and does not |
| 117 | match any negative refspec. Negative refspecs can be pattern refspecs. |
| 118 | They must only contain a _<src>_. |
| 119 | Fully spelled out hex object names are also not supported. |
| 120 | For example, `git push origin 'refs/heads/*' '^refs/heads/dev-*'` |
| 121 | will push all branches except for those starting with `dev-` |
| 122 | * If _<src>_ is empty, it deletes the _<dst>_ ref from the remote |
| 123 | repository. For example, `git push origin :dev` will |
| 124 | delete the `dev` branch. |
| 125 | * `tag <tag>` expands to `refs/tags/<tag>:refs/tags/<tag>`. |
| 126 | This is technically a special syntax for `git push` and not a refspec, |
| 127 | since in `git push origin tag v1.0` the arguments `tag` and `v1.0` |
| 128 | are separate. |
| 129 | * If the refspec can't be expanded unambiguously, error out |
| 130 | with an error indicating what was tried, and depending |
| 131 | on the `advice.pushUnqualifiedRefname` configuration (see |
| 132 | linkgit:git-config[1]) suggest what refs/ namespace you may have |
| 133 | wanted to push to. |
| 134 | |
| 135 | Not all updates are allowed: see PUSH RULES below for the details. |
| 136 | |
| 137 | `--all`:: |
| 138 | `--branches`:: |
| 139 | Push all branches (i.e. refs under `refs/heads/`); cannot be |
| 140 | used with other <refspec>. |
| 141 | |
| 142 | `--prune`:: |
| 143 | Remove remote branches that don't have a local counterpart. For example |
| 144 | a remote branch `tmp` will be removed if a local branch with the same |
| 145 | name doesn't exist any more. This also respects refspecs, e.g. |
| 146 | `git push --prune remote refs/heads/*:refs/tmp/*` would |
| 147 | make sure that remote `refs/tmp/foo` will be removed if `refs/heads/foo` |
| 148 | doesn't exist. |
| 149 | |
| 150 | `--mirror`:: |
| 151 | Instead of naming each ref to push, specifies that all |
| 152 | refs under `refs/` (which includes but is not |
| 153 | limited to `refs/heads/`, `refs/remotes/`, and `refs/tags/`) |
| 154 | be mirrored to the remote repository. Newly created local |
| 155 | refs will be pushed to the remote end, locally updated refs |
| 156 | will be force updated on the remote end, and deleted refs |
| 157 | will be removed from the remote end. This is the default |
| 158 | if the configuration option `remote.<remote>.mirror` is |
| 159 | set. |
| 160 | |
| 161 | `-n`:: |
| 162 | `--dry-run`:: |
| 163 | Do everything except actually send the updates. |
| 164 | |
| 165 | `--porcelain`:: |
| 166 | Produce machine-readable output. The output status line for each ref |
| 167 | will be tab-separated and sent to stdout instead of stderr. The full |
| 168 | symbolic names of the refs will be given. |
| 169 | |
| 170 | `-d`:: |
| 171 | `--delete`:: |
| 172 | All listed refs are deleted from the remote repository. This is |
| 173 | the same as prefixing all refs with a colon. |
| 174 | |
| 175 | `--tags`:: |
| 176 | All refs under `refs/tags` are pushed, in |
| 177 | addition to refspecs explicitly listed on the command |
| 178 | line. |
| 179 | |
| 180 | `--follow-tags`:: |
| 181 | Push all the refs that would be pushed without this option, |
| 182 | and also push annotated tags in `refs/tags` that are missing |
| 183 | from the remote but are pointing at commit-ish that are |
| 184 | reachable from the refs being pushed. This can also be specified |
| 185 | with configuration variable `push.followTags`. For more |
| 186 | information, see `push.followTags` in linkgit:git-config[1]. |
| 187 | |
| 188 | `--signed`:: |
| 189 | `--no-signed`:: |
| 190 | `--signed=(true|false|if-asked)`:: |
| 191 | GPG-sign the push request to update refs on the receiving |
| 192 | side, to allow it to be checked by the hooks and/or be |
| 193 | logged. Possible values are: |
| 194 | `false`;; |
| 195 | `--no-signed`;; |
| 196 | no signing will be attempted. |
| 197 | `true`;; |
| 198 | `--signed`;; |
| 199 | the push will fail if the server does not support signed pushes. |
| 200 | `if-asked`;; |
| 201 | sign if and only if the server supports signed pushes. The push |
| 202 | will also fail if the actual call to `gpg --sign` fails. See |
| 203 | linkgit:git-receive-pack[1] for the details on the receiving end. |
| 204 | |
| 205 | `--atomic`:: |
| 206 | `--no-atomic`:: |
| 207 | Use an atomic transaction on the remote side if available. |
| 208 | Either all refs are updated, or on error, no refs are updated. |
| 209 | If the server does not support atomic pushes the push will fail. |
| 210 | |
| 211 | `-o <option>`:: |
| 212 | `--push-option=<option>`:: |
| 213 | Transmit the given string to the server, which passes them to |
| 214 | the pre-receive as well as the post-receive hook. The given string |
| 215 | must not contain a _NUL_ or _LF_ character. |
| 216 | When multiple `--push-option=<option>` are given, they are |
| 217 | all sent to the other side in the order listed on the |
| 218 | command line. |
| 219 | When no `--push-option=<option>` is given from the command |
| 220 | line, the values of configuration variable `push.pushOption` |
| 221 | are used instead. |
| 222 | |
| 223 | `--receive-pack=<git-receive-pack>`:: |
| 224 | `--exec=<git-receive-pack>`:: |
| 225 | Path to the 'git-receive-pack' program on the remote |
| 226 | end. Sometimes useful when pushing to a remote |
| 227 | repository over ssh, and you do not have the program in |
| 228 | a directory on the default `$PATH`. |
| 229 | |
| 230 | `--force-with-lease`:: |
| 231 | `--no-force-with-lease`:: |
| 232 | `--force-with-lease=<refname>`:: |
| 233 | `--force-with-lease=<refname>:<expect>`:: |
| 234 | Usually, `git push` refuses to update a remote ref that is |
| 235 | not an ancestor of the local ref used to overwrite it. |
| 236 | + |
| 237 | This option overrides this restriction if the current value of the |
| 238 | remote ref is the expected value. `git push` fails otherwise. |
| 239 | + |
| 240 | Imagine that you have to rebase what you have already published. |
| 241 | You will have to bypass the "must fast-forward" rule in order to |
| 242 | replace the history you originally published with the rebased history. |
| 243 | If somebody else built on top of your original history while you are |
| 244 | rebasing, the tip of the branch at the remote may advance with their |
| 245 | commit, and blindly pushing with `--force` will lose their work. |
| 246 | + |
| 247 | This option allows you to say that you expect the history you are |
| 248 | updating is what you rebased and want to replace. If the remote ref |
| 249 | still points at the commit you specified, you can be sure that no |
| 250 | other people did anything to the ref. It is like taking a "lease" on |
| 251 | the ref without explicitly locking it, and the remote ref is updated |
| 252 | only if the "lease" is still valid. |
| 253 | + |
| 254 | `--force-with-lease` alone, without specifying the details, will protect |
| 255 | all remote refs that are going to be updated by requiring their |
| 256 | current value to be the same as the remote-tracking branch we have |
| 257 | for them. |
| 258 | + |
| 259 | `--force-with-lease=<refname>`, without specifying the expected value, will |
| 260 | protect _<refname>_ (alone), if it is going to be updated, by |
| 261 | requiring its current value to be the same as the remote-tracking |
| 262 | branch we have for it. |
| 263 | + |
| 264 | `--force-with-lease=<refname>:<expect>` will protect _<refname>_ (alone), |
| 265 | if it is going to be updated, by requiring its current value to be |
| 266 | the same as the specified value _<expect>_ (which is allowed to be |
| 267 | different from the remote-tracking branch we have for the refname, |
| 268 | or we do not even have to have such a remote-tracking branch when |
| 269 | this form is used). If _<expect>_ is the empty string, then the named ref |
| 270 | must not already exist. |
| 271 | + |
| 272 | Note that all forms other than `--force-with-lease=<refname>:<expect>` |
| 273 | that specifies the expected current value of the ref explicitly are |
| 274 | still experimental and their semantics may change as we gain experience |
| 275 | with this feature. |
| 276 | + |
| 277 | `--no-force-with-lease` will cancel all the previous `--force-with-lease` on the |
| 278 | command line. |
| 279 | + |
| 280 | A general note on safety: supplying this option without an expected |
| 281 | value, i.e. as `--force-with-lease` or `--force-with-lease=<refname>` |
| 282 | interacts very badly with anything that implicitly runs `git fetch` on |
| 283 | the remote to be pushed to in the background, e.g. `git fetch origin` |
| 284 | on your repository in a cronjob. |
| 285 | + |
| 286 | The protection it offers over `--force` is ensuring that subsequent |
| 287 | changes your work wasn't based on aren't clobbered, but this is |
| 288 | trivially defeated if some background process is updating refs in the |
| 289 | background. We don't have anything except the remote tracking info to |
| 290 | go by as a heuristic for refs you're expected to have seen & are |
| 291 | willing to clobber. |
| 292 | + |
| 293 | If your editor or some other system is running `git fetch` in the |
| 294 | background for you a way to mitigate this is to simply set up another |
| 295 | remote: |
| 296 | + |
| 297 | ---- |
| 298 | git remote add origin-push $(git config remote.origin.url) |
| 299 | git fetch origin-push |
| 300 | ---- |
| 301 | + |
| 302 | Now when the background process runs `git fetch origin` the references |
| 303 | on `origin-push` won't be updated, and thus commands like: |
| 304 | + |
| 305 | ---- |
| 306 | git push --force-with-lease origin-push |
| 307 | ---- |
| 308 | + |
| 309 | Will fail unless you manually run `git fetch origin-push`. This method |
| 310 | is of course entirely defeated by something that runs `git fetch |
| 311 | --all`, in that case you'd need to either disable it or do something |
| 312 | more tedious like: |
| 313 | + |
| 314 | ---- |
| 315 | git fetch # update 'master' from remote |
| 316 | git tag base master # mark our base point |
| 317 | git rebase -i master # rewrite some commits |
| 318 | git push --force-with-lease=master:base master:master |
| 319 | ---- |
| 320 | + |
| 321 | I.e. create a `base` tag for versions of the upstream code that you've |
| 322 | seen and are willing to overwrite, then rewrite history, and finally |
| 323 | force push changes to `master` if the remote version is still at |
| 324 | `base`, regardless of what your local `remotes/origin/master` has been |
| 325 | updated to in the background. |
| 326 | + |
| 327 | Alternatively, specifying `--force-if-includes` as an ancillary option |
| 328 | along with `--force-with-lease[=<refname>]` (i.e., without saying what |
| 329 | exact commit the ref on the remote side must be pointing at, or which |
| 330 | refs on the remote side are being protected) at the time of "push" will |
| 331 | verify if updates from the remote-tracking refs that may have been |
| 332 | implicitly updated in the background are integrated locally before |
| 333 | allowing a forced update. |
| 334 | |
| 335 | `-f`:: |
| 336 | `--force`:: |
| 337 | Usually, `git push` will refuse to update a branch that is not an |
| 338 | ancestor of the commit being pushed. |
| 339 | + |
| 340 | This flag disables that check, the other safety checks in PUSH RULES |
| 341 | below, and the checks in `--force-with-lease`. It can cause the remote |
| 342 | repository to lose commits; use it with care. |
| 343 | + |
| 344 | Note that `--force` applies to all the refs that are pushed, hence |
| 345 | using it with `push.default` set to `matching` or with multiple push |
| 346 | destinations configured with `remote.<name>.push` may overwrite refs |
| 347 | other than the current branch (including local refs that are |
| 348 | strictly behind their remote counterpart). To force a push to only |
| 349 | one branch, use a `+` in front of the refspec to push (e.g `git push |
| 350 | origin +master` to force a push to the `master` branch). See the |
| 351 | `<refspec>...` section above for details. |
| 352 | |
| 353 | `--force-if-includes`:: |
| 354 | `--no-force-if-includes`:: |
| 355 | Force an update only if the tip of the remote-tracking ref |
| 356 | has been integrated locally. |
| 357 | + |
| 358 | This option enables a check that verifies if the tip of the |
| 359 | remote-tracking ref is reachable from one of the "reflog" entries of |
| 360 | the local branch based in it for a rewrite. The check ensures that any |
| 361 | updates from the remote have been incorporated locally by rejecting the |
| 362 | forced update if that is not the case. |
| 363 | + |
| 364 | If the option is passed without specifying `--force-with-lease`, or |
| 365 | specified along with `--force-with-lease=<refname>:<expect>`, it is |
| 366 | a "no-op". |
| 367 | + |
| 368 | Specifying `--no-force-if-includes` disables this behavior. |
| 369 | |
| 370 | `--repo=<repository>`:: |
| 371 | This option is equivalent to the _<repository>_ argument. If both |
| 372 | are specified, the command-line argument takes precedence. |
| 373 | |
| 374 | `-u`:: |
| 375 | `--set-upstream`:: |
| 376 | For every branch that is up to date or successfully pushed, add |
| 377 | upstream (tracking) reference, used by argument-less |
| 378 | linkgit:git-pull[1] and other commands. For more information, |
| 379 | see `branch.<name>.merge` in linkgit:git-config[1]. |
| 380 | |
| 381 | `--thin`:: |
| 382 | `--no-thin`:: |
| 383 | These options are passed to linkgit:git-send-pack[1]. A thin transfer |
| 384 | significantly reduces the amount of sent data when the sender and |
| 385 | receiver share many of the same objects in common. The default is |
| 386 | `--thin`. |
| 387 | |
| 388 | `-q`:: |
| 389 | `--quiet`:: |
| 390 | Suppress all output, including the listing of updated refs, |
| 391 | unless an error occurs. Progress is not reported to the standard |
| 392 | error stream. |
| 393 | |
| 394 | `-v`:: |
| 395 | `--verbose`:: |
| 396 | Run verbosely. |
| 397 | |
| 398 | `--progress`:: |
| 399 | Progress status is reported on the standard error stream |
| 400 | by default when it is attached to a terminal, unless `-q` |
| 401 | is specified. This flag forces progress status even if the |
| 402 | standard error stream is not directed to a terminal. |
| 403 | |
| 404 | `--no-recurse-submodules`:: |
| 405 | `--recurse-submodules=(check|on-demand|only|no)`:: |
| 406 | May be used to make sure all submodule commits used by the |
| 407 | revisions to be pushed are available on a remote-tracking branch. |
| 408 | Possible values are: |
| 409 | `check`;; |
| 410 | Git will verify that all submodule commits that |
| 411 | changed in the revisions to be pushed are available on at least one |
| 412 | remote of the submodule. If any commits are missing the push will |
| 413 | be aborted and exit with non-zero status. |
| 414 | `on-demand`;; |
| 415 | all submodules that changed in the revisions to be pushed will be |
| 416 | pushed. If `on-demand` was not able to push all necessary revisions it will |
| 417 | also be aborted and exit with non-zero status. |
| 418 | `only`;; |
| 419 | all submodules will be pushed while the superproject is left |
| 420 | unpushed. |
| 421 | `no`;; |
| 422 | override the `push.recurseSubmodules` configuration variable when no |
| 423 | submodule recursion is required. Similar to using `--no-recurse-submodules`. |
| 424 | |
| 425 | + |
| 426 | When using `on-demand` or `only`, if a submodule has a |
| 427 | `push.recurseSubmodules=(on-demand|only)` or `submodule.recurse` configuration, |
| 428 | further recursion will occur. In this case, `only` is treated as `on-demand`. |
| 429 | |
| 430 | `--verify`:: |
| 431 | `--no-verify`:: |
| 432 | Toggle the pre-push hook (see linkgit:githooks[5]). The |
| 433 | default is `--verify`, giving the hook a chance to prevent the |
| 434 | push. With `--no-verify`, the hook is bypassed completely. |
| 435 | |
| 436 | `-4`:: |
| 437 | `--ipv4`:: |
| 438 | Use IPv4 addresses only, ignoring IPv6 addresses. |
| 439 | |
| 440 | `-6`:: |
| 441 | `--ipv6`:: |
| 442 | Use IPv6 addresses only, ignoring IPv4 addresses. |
| 443 | |
| 444 | include::urls-remotes.adoc[] |
| 445 | |
| 446 | [[REMOTE-GROUPS]] |
| 447 | REMOTE GROUPS |
| 448 | ------------- |
| 449 | |
| 450 | A remote group is a named list of remotes configured via `remotes.<name>` |
| 451 | in your git config: |
| 452 | |
| 453 | $ git config remotes.all-remotes "r1 r2 r3" |
| 454 | |
| 455 | When a group name is given as the `<repository>` argument, the push is |
| 456 | performed to each member remote in turn. The defining principle is: |
| 457 | |
| 458 | git push <options> all-remotes <args> |
| 459 | |
| 460 | is exactly equivalent to: |
| 461 | |
| 462 | git push <options> r1 <args> |
| 463 | git push <options> r2 <args> |
| 464 | ... |
| 465 | git push <options> rN <args> |
| 466 | |
| 467 | where r1, r2, ..., rN are the members of `all-remotes`. No special |
| 468 | behaviour is added or removed — the group is purely a shorthand for |
| 469 | running the same push command against each member remote individually. |
| 470 | |
| 471 | When pushing to a group of more than one remote, Git spawns a separate |
| 472 | `git push` subprocess for each member remote in sequence. Each subprocess |
| 473 | receives the same flags and refspecs as the original invocation. This |
| 474 | means that per-remote push mappings configured via `remote.<name>.push` |
| 475 | and mirror mode (`remote.<name>.mirror`) are evaluated independently for |
| 476 | each remote, and a mirror remote in the group cannot affect the push |
| 477 | behaviour of other non-mirror remotes in the same group. |
| 478 | |
| 479 | The `--atomic` option is not supported for group pushes, because atomicity |
| 480 | can only be guaranteed within a single transport connection to a single |
| 481 | remote. Git will refuse the invocation with an error if `--atomic` is |
| 482 | combined with a group name. |
| 483 | |
| 484 | If any member remote fails whether due to a push rejection (e.g. a |
| 485 | non-fast-forward update, a server-side hook refusing a ref) or a connection |
| 486 | error (e.g. the repository does not exist, authentication fails, or the |
| 487 | network is unreachable), Git reports the error and continues pushing to |
| 488 | the remaining remotes in the group. The overall exit code is non-zero if |
| 489 | any member push fails. |
| 490 | |
| 491 | This means the user is responsible for ensuring that the sequence of |
| 492 | individual pushes makes sense. If `git push r1`` would fail for a given |
| 493 | set of options and arguments, then `git push all-remotes` will fail in |
| 494 | the same way when it reaches r1. The group push does not do anything |
| 495 | special to make a failing individual push succeed. |
| 496 | |
| 497 | OUTPUT |
| 498 | ------ |
| 499 | |
| 500 | The output of "git push" depends on the transport method used; this |
| 501 | section describes the output when pushing over the Git protocol (either |
| 502 | locally or via ssh). |
| 503 | |
| 504 | The status of the push is output in tabular form, with each line |
| 505 | representing the status of a single ref. Each line is of the form: |
| 506 | |
| 507 | ------------------------------- |
| 508 | <flag> <summary> <from> -> <to> (<reason>) |
| 509 | ------------------------------- |
| 510 | |
| 511 | If `--porcelain` is used, then each line of the output is of the form: |
| 512 | |
| 513 | ------------------------------- |
| 514 | <flag> \t <from>:<to> \t <summary> (<reason>) |
| 515 | ------------------------------- |
| 516 | |
| 517 | The status of up-to-date refs is shown only if `--porcelain` or `--verbose` |
| 518 | option is used. |
| 519 | |
| 520 | _<flag>_:: |
| 521 | A single character indicating the status of the ref: |
| 522 | (space);; for a successfully pushed fast-forward; |
| 523 | `+`;; for a successful forced update; |
| 524 | `-`;; for a successfully deleted ref; |
| 525 | `*`;; for a successfully pushed new ref; |
| 526 | `!`;; for a ref that was rejected or failed to push; and |
| 527 | `=`;; for a ref that was up to date and did not need pushing. |
| 528 | |
| 529 | _<summary>_:: |
| 530 | For a successfully pushed ref, the summary shows the old and new |
| 531 | values of the ref in a form suitable for using as an argument to |
| 532 | `git log` (this is `<old>..<new>` in most cases, and |
| 533 | `<old>...<new>` for forced non-fast-forward updates). |
| 534 | + |
| 535 | For a failed update, more details are given: |
| 536 | + |
| 537 | -- |
| 538 | rejected:: |
| 539 | Git did not try to send the ref at all, typically because it |
| 540 | is not a fast-forward and you did not force the update. |
| 541 | |
| 542 | remote rejected:: |
| 543 | The remote end refused the update. Usually caused by a hook |
| 544 | on the remote side, or because the remote repository has one |
| 545 | of the following safety options in effect: |
| 546 | `receive.denyCurrentBranch` (for pushes to the checked out |
| 547 | branch), `receive.denyNonFastForwards` (for forced |
| 548 | non-fast-forward updates), `receive.denyDeletes` or |
| 549 | `receive.denyDeleteCurrent`. See linkgit:git-config[1]. |
| 550 | |
| 551 | remote failure:: |
| 552 | The remote end did not report the successful update of the ref, |
| 553 | perhaps because of a temporary error on the remote side, a |
| 554 | break in the network connection, or other transient error. |
| 555 | -- |
| 556 | |
| 557 | from:: |
| 558 | The name of the local ref being pushed, minus its |
| 559 | `refs/<type>/` prefix. In the case of deletion, the |
| 560 | name of the local ref is omitted. |
| 561 | |
| 562 | to:: |
| 563 | The name of the remote ref being updated, minus its |
| 564 | `refs/<type>/` prefix. |
| 565 | |
| 566 | reason:: |
| 567 | A human-readable explanation. In the case of successfully pushed |
| 568 | refs, no explanation is needed. For a failed ref, the reason for |
| 569 | failure is described. |
| 570 | |
| 571 | PUSH RULES |
| 572 | ---------- |
| 573 | |
| 574 | As a safety feature, the `git push` command only allows certain kinds of |
| 575 | updates to prevent you from accidentally losing data on the remote. |
| 576 | |
| 577 | Because branches and tags are intended to be used differently, the |
| 578 | safety rules for pushing to a branch are different from the rules |
| 579 | for pushing to a tag. In the following rules "update" means any |
| 580 | modifications except deletions and creations. Deletions and creations |
| 581 | are always allowed, except when forbidden by configuration or hooks. |
| 582 | |
| 583 | 1. If the push destination is a **branch** (`refs/heads/*`): only |
| 584 | fast-forward updates are allowed, which means the destination must be |
| 585 | an ancestor of the source commit. The source must be a commit. |
| 586 | 2. If the push destination is a **tag** (`refs/tags/*`): all updates will |
| 587 | be rejected. The source can be any object. |
| 588 | 3. If the push destination is not a branch or tag: |
| 589 | * If the source is a tree or blob object, any updates will be rejected |
| 590 | * If the source is a tag or commit object, any fast-forward update |
| 591 | is allowed, even in cases where what's being fast-forwarded is not a |
| 592 | commit, but a tag object which happens to point to a new commit which |
| 593 | is a fast-forward of the commit the last tag (or commit) it's |
| 594 | replacing. Replacing a tag with an entirely different tag is also |
| 595 | allowed, if it points to the same commit, as well as pushing a peeled |
| 596 | tag, i.e. pushing the commit that existing tag object points to, or a |
| 597 | new tag object which an existing commit points to. |
| 598 | |
| 599 | You can override these rules by passing `--force` or by adding the |
| 600 | optional leading `+` to a refspec. The only exceptions are that no |
| 601 | amount of forcing will make a branch accept a non-commit object, |
| 602 | and forcing won't make the remote repository accept a push that it's |
| 603 | configured to deny. |
| 604 | |
| 605 | Hooks and configuration can also override or amend these rules, |
| 606 | see e.g. `receive.denyNonFastForwards` and `receive.denyDeletes` |
| 607 | in linkgit:git-config[1] and `pre-receive` and `update` in |
| 608 | linkgit:githooks[5]. |
| 609 | |
| 610 | NOTE ABOUT FAST-FORWARDS |
| 611 | ------------------------ |
| 612 | |
| 613 | When an update changes a branch (or more in general, a ref) that used to |
| 614 | point at commit A to point at another commit B, it is called a |
| 615 | fast-forward update if and only if B is a descendant of A. |
| 616 | |
| 617 | In a fast-forward update from A to B, the set of commits that the original |
| 618 | commit A built on top of is a subset of the commits the new commit B |
| 619 | builds on top of. Hence, it does not lose any history. |
| 620 | |
| 621 | In contrast, a non-fast-forward update will lose history. For example, |
| 622 | suppose you and somebody else started at the same commit X, and you built |
| 623 | a history leading to commit B while the other person built a history |
| 624 | leading to commit A. The history looks like this: |
| 625 | |
| 626 | ---------------- |
| 627 | |
| 628 | B |
| 629 | / |
| 630 | ---X---A |
| 631 | |
| 632 | ---------------- |
| 633 | |
| 634 | Further suppose that the other person already pushed changes leading to A |
| 635 | back to the original repository from which you two obtained the original |
| 636 | commit X. |
| 637 | |
| 638 | The push done by the other person updated the branch that used to point at |
| 639 | commit X to point at commit A. It is a fast-forward. |
| 640 | |
| 641 | But if you try to push, you will attempt to update the branch (that |
| 642 | now points at A) with commit B. This does _not_ fast-forward. If you did |
| 643 | so, the changes introduced by commit A will be lost, because everybody |
| 644 | will now start building on top of B. |
| 645 | |
| 646 | The command by default does not allow an update that is not a fast-forward |
| 647 | to prevent such loss of history. |
| 648 | |
| 649 | If you do not want to lose your work (history from X to B) or the work by |
| 650 | the other person (history from X to A), you would need to first fetch the |
| 651 | history from the repository, create a history that contains changes done |
| 652 | by both parties, and push the result back. |
| 653 | |
| 654 | You can perform "git pull", resolve potential conflicts, and "git push" |
| 655 | the result. A "git pull" will create a merge commit C between commits A |
| 656 | and B. |
| 657 | |
| 658 | ---------------- |
| 659 | |
| 660 | B---C |
| 661 | / / |
| 662 | ---X---A |
| 663 | |
| 664 | ---------------- |
| 665 | |
| 666 | Updating A with the resulting merge commit will fast-forward and your |
| 667 | push will be accepted. |
| 668 | |
| 669 | Alternatively, you can rebase your change between X and B on top of A, |
| 670 | with `git pull --rebase`, and push the result back. The rebase will |
| 671 | create a new commit D that builds the change between X and B on top of |
| 672 | A. |
| 673 | |
| 674 | ---------------- |
| 675 | |
| 676 | B D |
| 677 | / / |
| 678 | ---X---A |
| 679 | |
| 680 | ---------------- |
| 681 | |
| 682 | Again, updating A with this commit will fast-forward and your push will be |
| 683 | accepted. |
| 684 | |
| 685 | There is another common situation where you may encounter non-fast-forward |
| 686 | rejection when you try to push, and it is possible even when you are |
| 687 | pushing into a repository nobody else pushes into. After you push commit |
| 688 | A yourself (in the first picture in this section), replace it with `git |
| 689 | commit --amend` to produce commit B, and you try to push it out, because |
| 690 | forgot that you have pushed A out already. In such a case, and only if |
| 691 | you are certain that nobody in the meantime fetched your earlier commit A |
| 692 | (and started building on top of it), you can run `git push --force` to |
| 693 | overwrite it. In other words, `git push --force` is a method reserved for |
| 694 | a case where you do mean to lose history. |
| 695 | |
| 696 | |
| 697 | EXAMPLES |
| 698 | -------- |
| 699 | |
| 700 | `git push`:: |
| 701 | Works like `git push <remote>`, where <remote> is the |
| 702 | current branch's remote (or `origin`, if no remote is |
| 703 | configured for the current branch). |
| 704 | |
| 705 | `git push origin`:: |
| 706 | Without additional configuration, pushes the current branch to |
| 707 | the configured upstream (`branch.<name>.merge` configuration |
| 708 | variable) if it has the same name as the current branch, and |
| 709 | errors out without pushing otherwise. |
| 710 | + |
| 711 | The default behavior of this command when no _<refspec>_ is given can be |
| 712 | configured by setting the `push` option of the remote, or the `push.default` |
| 713 | configuration variable. |
| 714 | + |
| 715 | For example, to default to pushing only the current branch to `origin` |
| 716 | use `git config remote.origin.push HEAD`. Any valid _<refspec>_ (like |
| 717 | the ones in the examples below) can be configured as the default for |
| 718 | `git push origin`. |
| 719 | |
| 720 | `git push origin :`:: |
| 721 | Push "matching" branches to `origin`. See |
| 722 | _<refspec>_ in the <<OPTIONS,OPTIONS>> section above for a |
| 723 | description of "matching" branches. |
| 724 | |
| 725 | `git push origin master`:: |
| 726 | Find a ref that matches `master` in the source repository |
| 727 | (most likely, it would find `refs/heads/master`), and update |
| 728 | the same ref (e.g. `refs/heads/master`) in `origin` repository |
| 729 | with it. If `master` did not exist remotely, it would be |
| 730 | created. |
| 731 | |
| 732 | `git push origin HEAD`:: |
| 733 | A handy way to push the current branch to the same name on the |
| 734 | remote. |
| 735 | |
| 736 | `git push mothership master:satellite/master dev:satellite/dev`:: |
| 737 | Use the source ref that matches `master` (e.g. `refs/heads/master`) |
| 738 | to update the ref that matches `satellite/master` (most probably |
| 739 | `refs/remotes/satellite/master`) in the `mothership` repository; |
| 740 | do the same for `dev` and `satellite/dev`. |
| 741 | + |
| 742 | See the section describing `<refspec>...` above for a discussion of |
| 743 | the matching semantics. |
| 744 | + |
| 745 | This is to emulate `git fetch` run on the `mothership` using `git |
| 746 | push` that is run in the opposite direction in order to integrate |
| 747 | the work done on `satellite`, and is often necessary when you can |
| 748 | only make connection in one way (i.e. satellite can ssh into |
| 749 | mothership but mothership cannot initiate connection to satellite |
| 750 | because the latter is behind a firewall or does not run sshd). |
| 751 | + |
| 752 | After running this `git push` on the `satellite` machine, you would |
| 753 | ssh into the `mothership` and run `git merge` there to complete the |
| 754 | emulation of `git pull` that were run on `mothership` to pull changes |
| 755 | made on `satellite`. |
| 756 | |
| 757 | `git push origin HEAD:master`:: |
| 758 | Push the current branch to the remote ref matching `master` in the |
| 759 | `origin` repository. This form is convenient to push the current |
| 760 | branch without thinking about its local name. |
| 761 | |
| 762 | `git push origin master:refs/heads/experimental`:: |
| 763 | Create the branch `experimental` in the `origin` repository |
| 764 | by copying the current `master` branch. This form is only |
| 765 | needed to create a new branch or tag in the remote repository when |
| 766 | the local name and the remote name are different; otherwise, |
| 767 | the ref name on its own will work. |
| 768 | |
| 769 | `git push origin :experimental`:: |
| 770 | Find a ref that matches `experimental` in the `origin` repository |
| 771 | (e.g. `refs/heads/experimental`), and delete it. |
| 772 | |
| 773 | `git push origin +dev:master`:: |
| 774 | Update the origin repository's master branch with the dev branch, |
| 775 | allowing non-fast-forward updates. *This can leave unreferenced |
| 776 | commits dangling in the origin repository.* Consider the |
| 777 | following situation, where a fast-forward is not possible: |
| 778 | + |
| 779 | ---- |
| 780 | o---o---o---A---B origin/master |
| 781 | \ |
| 782 | X---Y---Z dev |
| 783 | ---- |
| 784 | + |
| 785 | The above command would change the origin repository to |
| 786 | + |
| 787 | ---- |
| 788 | A---B (unnamed branch) |
| 789 | / |
| 790 | o---o---o---X---Y---Z master |
| 791 | ---- |
| 792 | + |
| 793 | Commits A and B would no longer belong to a branch with a symbolic name, |
| 794 | and so would be unreachable. As such, these commits would be removed by |
| 795 | a `git gc` command on the origin repository. |
| 796 | |
| 797 | include::transfer-data-leaks.adoc[] |
| 798 | |
| 799 | [[CONFIGURATION]] |
| 800 | CONFIGURATION |
| 801 | ------------- |
| 802 | |
| 803 | include::includes/cmd-config-section-all.adoc[] |
| 804 | |
| 805 | include::config/push.adoc[] |
| 806 | |
| 807 | GIT |
| 808 | --- |
| 809 | Part of the linkgit:git[1] suite |