From: Junio C Hamano Date: Tue, 9 Feb 2010 00:49:22 +0000 (-0800) Subject: Merge branch 'jc/maint-push-doc-status' into maint X-Git-Tag: v1.6.6.2~12 X-Git-Url: https://git.lorimer.id.au/gitweb.git/diff_plain/a598331f952b5bd89f72fcf20a44ab3aa2918b3f?hp=-c Merge branch 'jc/maint-push-doc-status' into maint * jc/maint-push-doc-status: git-push: document all the status flags used in the output --- a598331f952b5bd89f72fcf20a44ab3aa2918b3f diff --combined Documentation/git-push.txt index 52c0538df5,5d21ca8850..ab1bf99fdb --- a/Documentation/git-push.txt +++ b/Documentation/git-push.txt @@@ -9,7 -9,7 +9,7 @@@ git-push - Update remote refs along wit SYNOPSIS -------- [verse] -'git push' [--all | --mirror | --tags] [--dry-run] [--receive-pack=] +'git push' [--all | --mirror | --tags] [-n | --dry-run] [--receive-pack=] [--repo=] [-f | --force] [-v | --verbose] [ ...] @@@ -50,9 -50,9 +50,9 @@@ updated + The object referenced by is used to update the reference on the remote side, but by default this is only allowed if the -update can fast forward . By having the optional leading `{plus}`, +update can fast-forward . By having the optional leading `{plus}`, you can tell git to update the ref even when the update is not a -fast forward. This does *not* attempt to merge into . See +fast-forward. This does *not* attempt to merge into . See EXAMPLES below for details. + `tag ` means the same as `refs/tags/:refs/tags/`. @@@ -60,7 -60,7 +60,7 @@@ Pushing an empty allows you to delete the ref from the remote repository. + -The special refspec `:` (or `{plus}:` to allow non-fast forward updates) +The special refspec `:` (or `{plus}:` to allow non-fast-forward updates) directs git to push "matching" branches: for every branch that exists on the local side, the remote side is updated if a branch of the same name already exists on the remote side. This is the default operation mode @@@ -82,7 -82,6 +82,7 @@@ nor in any Push line of the correspondi if the configuration option `remote..mirror` is set. +-n:: --dry-run:: Do everything except actually send the updates. @@@ -138,11 -137,6 +138,11 @@@ useful if you write an alias or script --verbose:: Run verbosely. +-q:: +--quiet:: + Suppress all output, including the listing of updated refs, + unless an error occurs. + include::urls-remotes.txt[] OUTPUT @@@ -165,21 -159,26 +165,26 @@@ If --porcelain is used, then each line \t : \t () ------------------------------- + The status of up-to-date refs is shown only if --porcelain or --verbose + option is used. + flag:: - A single character indicating the status of the ref. This is - blank for a successfully pushed ref, `!` for a ref that was - rejected or failed to push, and '=' for a ref that was up to - date and did not need pushing (note that the status of up to - date refs is shown only when `git push` is running verbosely). + A single character indicating the status of the ref: + (space);; for a successfully pushed fast-forward; + `{plus}`;; for a successful forced update; + `-`;; for a successfully deleted ref; + `*`;; for a successfully pushed new ref; + `!`;; for a ref that was rejected or failed to push; and + `=`;; for a ref that was up to date and did not need pushing. summary:: For a successfully pushed ref, the summary shows the old and new values of the ref in a form suitable for using as an argument to `git log` (this is `..` in most cases, and - `...` for forced non-fast forward updates). For a + `...` for forced non-fast-forward updates). For a failed update, more details are given for the failure. The string `rejected` indicates that git did not try to send the - ref at all (typically because it is not a fast forward). The + ref at all (typically because it is not a fast-forward). The string `remote rejected` indicates that the remote end refused the update; this rejection is typically caused by a hook on the remote side. The string `remote failure` indicates that the @@@ -201,92 -200,6 +206,92 @@@ reason: refs, no explanation is needed. For a failed ref, the reason for failure is described. +Note about fast-forwards +------------------------ + +When an update changes a branch (or more in general, a ref) that used to +point at commit A to point at another commit B, it is called a +fast-forward update if and only if B is a descendant of A. + +In a fast-forward update from A to B, the set of commits that the original +commit A built on top of is a subset of the commits the new commit B +builds on top of. Hence, it does not lose any history. + +In contrast, a non-fast-forward update will lose history. For example, +suppose you and somebody else started at the same commit X, and you built +a history leading to commit B while the other person built a history +leading to commit A. The history looks like this: + +---------------- + + B + / + ---X---A + +---------------- + +Further suppose that the other person already pushed changes leading to A +back to the original repository you two obtained the original commit X. + +The push done by the other person updated the branch that used to point at +commit X to point at commit A. It is a fast-forward. + +But if you try to push, you will attempt to update the branch (that +now points at A) with commit B. This does _not_ fast-forward. If you did +so, the changes introduced by commit A will be lost, because everybody +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 +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. + +You can perform "git pull", resolve potential conflicts, and "git push" +the result. A "git pull" will create a merge commit C between commits A +and B. + +---------------- + + B---C + / / + ---X---A + +---------------- + +Updating A with the resulting merge commit will fast-forward and your +push will be accepted. + +Alternatively, you can rebase your change between X and B on top of A, +with "git pull --rebase", and push the result back. The rebase will +create a new commit D that builds the change between X and B on top of +A. + +---------------- + + B D + / / + ---X---A + +---------------- + +Again, updating A with this commit will fast-forward and your push will be +accepted. + +There is another common situation where you may encounter non-fast-forward +rejection when you try to push, and it is possible even when you are +pushing into a repository nobody else pushes into. After you push commit +A yourself (in the first picture in this section), replace it with "git +commit --amend" to produce commit B, and you try to push it out, because +forgot that you have pushed A out already. In such a case, and only if +you are certain that nobody in the meantime fetched your earlier commit A +(and started building on top of it), you can run "git push --force" to +overwrite it. In other words, "git push --force" is a method reserved for +a case where you do mean to lose history. + + Examples -------- @@@ -347,9 -260,9 +352,9 @@@ git push origin :experimental: git push origin {plus}dev:master:: Update the origin repository's master branch with the dev branch, - allowing non-fast forward updates. *This can leave unreferenced + allowing non-fast-forward updates. *This can leave unreferenced commits dangling in the origin repository.* Consider the - following situation, where a fast forward is not possible: + following situation, where a fast-forward is not possible: + ---- o---o---o---A---B origin/master