Docs: Expand explanation of the use of + in git push refspecs.
Signed-off-by: Marc Branchaud <marcnarc@xiplink.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Marc Branchaud committed
Feb 19, 2009 at 12:39 UTC
149f6ddfb324b677472192d4aa1ddc350cf49e80
1 file changed
+31
-5
Documentation/git-push.txt
+31
-5
@@ -48,17 +48,19 @@ push. Arbitrary expressions cannot be used here, an actual ref must
48
be named. If `:`<dst> is omitted, the same ref as <src> will be
49
updated.
50
+
51
-The object referenced by <src> is used to fast forward the ref <dst>
52
-on the remote side. If the optional leading plus `{plus}` is used, the
53
-remote ref is updated even if it does not result in a fast forward
54
-update.
51
+The object referenced by <src> is used to update the <dst> reference
52
+on the remote side, but by default this is only allowed if the
53
+update can fast forward <dst>. By having the optional leading `{plus}`,
54
+you can tell git to update the <dst> ref even when the update is not a
55
+fast forward. This does *not* attempt to merge <src> into <dst>. See
56
+EXAMPLES below for details.
57
+
58
`tag <tag>` means the same as `refs/tags/<tag>:refs/tags/<tag>`.
59
+
60
Pushing an empty <src> allows you to delete the <dst> ref from
61
the remote repository.
62
+
61
-The special refspec `:` (or `+:` to allow non-fast forward updates)
63
+The special refspec `:` (or `{plus}:` to allow non-fast forward updates)
64
directs git to push "matching" branches: for every branch that exists on
65
the local side, the remote side is updated if a branch of the same name
66
already exists on the remote side. This is the default operation mode
@@ -218,6 +220,30 @@ git push origin :experimental::
220
Find a ref that matches `experimental` in the `origin` repository
221
(e.g. `refs/heads/experimental`), and delete it.
222
223
+git push origin {plus}dev:master::
224
+ Update the origin repository's master branch with the dev branch,
225
+ allowing non-fast forward updates. *This can leave unreferenced
226
+ commits dangling in the origin repository.* Consider the
227
+ following situation, where a fast forward is not possible:
228
++
229
+----
230
+ o---o---o---A---B origin/master
231
+ \
232
+ X---Y---Z dev
233
+----
234
++
235
+The above command would change the origin repository to
236
++
237
+----
238
+ A---B (unnamed branch)
239
+ /
240
+ o---o---o---X---Y---Z master
241
+----
242
++
243
+Commits A and B would no longer belong to a branch with a symbolic name,
244
+and so would be unreachable. As such, these commits would be removed by
245
+a `git gc` command on the origin repository.
246
+
247
248
Author
249
------