diff options
Diffstat (limited to 'Documentation/git-push.txt')
| -rw-r--r-- | Documentation/git-push.txt | 148 |
1 files changed, 107 insertions, 41 deletions
diff --git a/Documentation/git-push.txt b/Documentation/git-push.txt index f7dfe48d28..1495e3416c 100644 --- a/Documentation/git-push.txt +++ b/Documentation/git-push.txt @@ -9,8 +9,11 @@ git-push - Update remote refs along with associated objects SYNOPSIS -------- [verse] -'git push' [--all | --mirror | --tags] [--follow-tags] [-n | --dry-run] [--receive-pack=<git-receive-pack>] - [--repo=<repository>] [-f | --force] [--prune] [-v | --verbose] [-u | --set-upstream] +'git push' [--all | --mirror | --tags] [--follow-tags] [--atomic] [-n | --dry-run] [--receive-pack=<git-receive-pack>] + [--repo=<repository>] [-f | --force] [--prune] [-v | --verbose] + [-u | --set-upstream] + [--[no-]signed|--sign=(true|false|if-asked)] + [--force-with-lease[=<refname>[:<expect>]]] [--no-verify] [<repository> [<refspec>...]] DESCRIPTION @@ -32,7 +35,7 @@ When the command line does not specify what to push with `<refspec>...` arguments or `--all`, `--mirror`, `--tags` options, the command finds the default `<refspec>` by consulting `remote.*.push` configuration, and if it is not found, honors `push.default` configuration to decide -what to push (See gitlink:git-config[1] for the meaning of `push.default`). +what to push (See linkgit:git-config[1] for the meaning of `push.default`). OPTIONS[[OPTIONS]] @@ -55,8 +58,13 @@ it can be any arbitrary "SHA-1 expression", such as `master~4` or + The <dst> tells which ref on the remote side is updated with this push. Arbitrary expressions cannot be used here, an actual ref must -be named. If `:`<dst> is omitted, the same ref as <src> will be -updated. +be named. +If `git push [<repository>]` without any `<refspec>` argument is set to +update some ref at the destination with `<src>` with +`remote.<repository>.push` configuration variable, `:<dst>` part can +be omitted---such a push will update a ref that `<src>` normally updates +without any `<refspec>` on the command line. Otherwise, missing +`:<dst>` means to update the same ref as the `<src>`. + The object referenced by <src> is used to update the <dst> reference on the remote side. By default this is only allowed if <dst> is not @@ -77,8 +85,8 @@ the local side, the remote side is updated if a branch of the same name already exists on the remote side. --all:: - Instead of naming each ref to push, specifies that all - refs under `refs/heads/` be pushed. + Push all branches (i.e. refs under `refs/heads/`); cannot be + used with other <refspec>. --prune:: Remove remote branches that don't have a local counterpart. For example @@ -120,8 +128,26 @@ already exists on the remote side. --follow-tags:: Push all the refs that would be pushed without this option, and also push annotated tags in `refs/tags` that are missing - from the remote but are pointing at committish that are - reachable from the refs being pushed. + from the remote but are pointing at commit-ish that are + reachable from the refs being pushed. This can also be specified + with configuration variable 'push.followTags'. For more + information, see 'push.followTags' in linkgit:git-config[1]. + +--[no-]signed:: +--sign=(true|false|if-asked):: + GPG-sign the push request to update refs on the receiving + side, to allow it to be checked by the hooks and/or be + logged. If `false` or `--no-signed`, no signing will be + attempted. If `true` or `--signed`, the push will fail if the + server does not support signed pushes. If set to `if-asked`, + sign if and only if the server supports signed pushes. The push + will also fail if the actual call to `gpg --sign` fails. See + linkgit:git-receive-pack[1] for the details on the receiving end. + +--[no-]atomic:: + Use an atomic transaction on the remote side if available. + Either all refs are updated, or on error, no refs are updated. + If the server does not support atomic pushes the push will fail. --receive-pack=<git-receive-pack>:: --exec=<git-receive-pack>:: @@ -130,39 +156,77 @@ already exists on the remote side. repository over ssh, and you do not have the program in a directory on the default $PATH. +--[no-]force-with-lease:: +--force-with-lease=<refname>:: +--force-with-lease=<refname>:<expect>:: + Usually, "git push" refuses to update a remote ref that is + not an ancestor of the local ref used to overwrite it. ++ +This option overrides this restriction if the current value of the +remote ref is the expected value. "git push" fails otherwise. ++ +Imagine that you have to rebase what you have already published. +You will have to bypass the "must fast-forward" rule in order to +replace the history you originally published with the rebased history. +If somebody else built on top of your original history while you are +rebasing, the tip of the branch at the remote may advance with her +commit, and blindly pushing with `--force` will lose her work. ++ +This option allows you to say that you expect the history you are +updating is what you rebased and want to replace. If the remote ref +still points at the commit you specified, you can be sure that no +other people did anything to the ref. It is like taking a "lease" on +the ref without explicitly locking it, and the remote ref is updated +only if the "lease" is still valid. ++ +`--force-with-lease` alone, without specifying the details, will protect +all remote refs that are going to be updated by requiring their +current value to be the same as the remote-tracking branch we have +for them. ++ +`--force-with-lease=<refname>`, without specifying the expected value, will +protect the named ref (alone), if it is going to be updated, by +requiring its current value to be the same as the remote-tracking +branch we have for it. ++ +`--force-with-lease=<refname>:<expect>` will protect the named ref (alone), +if it is going to be updated, by requiring its current value to be +the same as the specified value <expect> (which is allowed to be +different from the remote-tracking branch we have for the refname, +or we do not even have to have such a remote-tracking branch when +this form is used). ++ +Note that all forms other than `--force-with-lease=<refname>:<expect>` +that specifies the expected current value of the ref explicitly are +still experimental and their semantics may change as we gain experience +with this feature. ++ +"--no-force-with-lease" will cancel all the previous --force-with-lease on the +command line. + -f:: --force:: Usually, the command refuses to update a remote ref that is not an ancestor of the local ref used to overwrite it. - This flag disables the check. This can cause the - remote repository to lose commits; use it with care. - Note that `--force` applies to all the refs that are pushed, - hence using it with `push.default` set to `matching` or with - multiple push destinations configured with `remote.*.push` - may overwrite refs other than the current branch (including - local refs that are strictly behind their remote counterpart). - To force a push to only one branch, use a `+` in front of the - refspec to push (e.g `git push origin +master` to force a push - to the `master` branch). See the `<refspec>...` section above - for details. - ---repo=<repository>:: - This option is only relevant if no <repository> argument is - passed in the invocation. In this case, 'git push' derives the - remote name from the current branch: If it tracks a remote - branch, then that remote repository is pushed to. Otherwise, - the name "origin" is used. For this latter case, this option - can be used to override the name "origin". In other words, - the difference between these two commands + Also, when `--force-with-lease` option is used, the command refuses + to update a remote ref whose current value does not match + what is expected. + --------------------------- -git push public #1 -git push --repo=public #2 --------------------------- +This flag disables these checks, and can cause the remote repository +to lose commits; use it with care. + -is that #1 always pushes to "public" whereas #2 pushes to "public" -only if the current branch does not track a remote branch. This is -useful if you write an alias or script around 'git push'. +Note that `--force` applies to all the refs that are pushed, hence +using it with `push.default` set to `matching` or with multiple push +destinations configured with `remote.*.push` may overwrite refs +other than the current branch (including local refs that are +strictly behind their remote counterpart). To force a push to only +one branch, use a `+` in front of the refspec to push (e.g `git push +origin +master` to force a push to the `master` branch). See the +`<refspec>...` section above for details. + +--repo=<repository>:: + This option is equivalent to the <repository> argument. If both + are specified, the command-line argument takes precedence. -u:: --set-upstream:: @@ -206,8 +270,8 @@ useful if you write an alias or script around 'git push'. --[no-]verify:: Toggle the pre-push hook (see linkgit:githooks[5]). The - default is \--verify, giving the hook a chance to prevent the - push. With \--no-verify, the hook is bypassed completely. + default is --verify, giving the hook a chance to prevent the + push. With --no-verify, the hook is bypassed completely. include::urls-remotes.txt[] @@ -325,7 +389,7 @@ will now start building on top of B. The command by default does not allow an update that is not a fast-forward to prevent such loss of history. -If you do not want to lose your work (history from X to B) nor the work by +If you do not want to lose your work (history from X to B) or the work by the other person (history from X to A), you would need to first fetch the history from the repository, create a history that contains changes done by both parties, and push the result back. @@ -382,8 +446,10 @@ Examples configured for the current branch). `git push origin`:: - Without additional configuration, works like - `git push origin :`. + Without additional configuration, pushes the current branch to + the configured upstream (`remote.origin.merge` configuration + variable) if it has the same name as the current branch, and + errors out without pushing otherwise. + The default behavior of this command when no <refspec> is given can be configured by setting the `push` option of the remote, or the `push.default` |