[PATCH] Expand explanation of the use of + in git push refspecs.
Signed-off-by: Marc Branchaud <marcnarc@xiplink.com>
---
Documentation/git-push.txt | 40 ++++++++++++++++++++++++++++++++--------
1 files changed, 32 insertions(+), 8 deletions(-)
diff --git a/Documentation/git-push.txt b/Documentation/git-push.txt
index 7d1eced..4cb13a1 100644
--- a/Documentation/git-push.txt
+++ b/Documentation/git-push.txt
@@ -50,20 +50,21 @@ updated.
+
The object referenced by <src> is used to fast forward the ref <dst>
on the remote side. If the optional leading plus `{plus}` is used, the
-remote ref is updated even if it does not result in a fast forward
-update.
+remote ref is *overwritten* with the local ref. (The use of `{plus}`
+is recommended only for private, unshared repositories.) See EXAMPLES
+below for details.
+
`tag <tag>` means the same as `refs/tags/<tag>:refs/tags/<tag>`.
+
Pushing an empty <src> allows you to delete the <dst> ref from
the remote repository.
+
-The special refspec `:` (or `+:` 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
-if no explicit refspec is found (that is neither on the command line
-nor in any Push line of the corresponding remotes file---see below).
+The special refspec `:` (or `{plus}:` to allow overwriting) 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 if no
+explicit refspec is found (that is neither on the command line nor in
+any Push line of the corresponding remotes file---see below).
--all::
Instead of naming each ref to push, specifies that all
@@ -218,6 +219,29 @@ git push origin :experimental::
Find a ref that matches `experimental` in the `origin` repository
(e.g. `refs/heads/experimental`), and delete it.
+git push origin {plus}dev:master::
+ *Overwrite* the origin repository's master branch with the dev
+ branch. *This can abandon commits in the origin repository.*
+ Consider the following situation:
++
+----
+ o---o---o---A---B origin/master
+ \
+ X---Y---Z dev
+----
++
+The above command would change the origin repository to
++
+----
+ A---B (unnamed branch)
+ /
+ o---o---o---X---Y---Z origin/master
+----
++
+That is, commits A and B would belong to an unreachable branch without a
+symbolic name. As such, these commits would be removed by a `git gc`
+command on the origin repository.
+
Author
------
--
1.6.1.2.390.gba743
Marc Branchaud <marcnarc@xiplink.com>