* [PATCH] Expand explanation of the use of + in git push refspecs.
@ 2009-02-19 17:39 Marc Branchaud
2009-02-19 17:39 ` [PATCHv2] Docs: " Marc Branchaud
` (2 more replies)
0 siblings, 3 replies; 7+ messages in thread
From: Marc Branchaud @ 2009-02-19 17:39 UTC (permalink / raw)
To: git; +Cc: srabbelier
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
^ permalink raw reply related [flat|nested] 7+ messages in thread
* [PATCHv2] Docs: Expand explanation of the use of + in git push refspecs.
2009-02-19 17:39 [PATCH] Expand explanation of the use of + in git push refspecs Marc Branchaud
@ 2009-02-19 17:39 ` Marc Branchaud
2009-02-24 17:39 ` Junio C Hamano
2009-02-19 18:20 ` [PATCH] " Sverre Rabbelier
2009-02-20 5:04 ` Junio C Hamano
2 siblings, 1 reply; 7+ messages in thread
From: Marc Branchaud @ 2009-02-19 17:39 UTC (permalink / raw)
To: git; +Cc: srabbelier
Signed-off-by: Marc Branchaud <marcnarc@xiplink.com>
---
This version incorporates comments from Junio and Sverre.
Documentation/git-push.txt | 36 +++++++++++++++++++++++++++++++-----
1 files changed, 31 insertions(+), 5 deletions(-)
diff --git a/Documentation/git-push.txt b/Documentation/git-push.txt
index 7d1eced..2fae4fd 100644
--- a/Documentation/git-push.txt
+++ b/Documentation/git-push.txt
@@ -48,17 +48,19 @@ 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.
+
-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.
+The object referenced by <src> is used to update the <dst> reference
+on the remote side, but by default this is only allowed if the
+update can fast forward <dst>. By having the optional leading `{plus}`,
+you can tell git to update the <dst> ref even when the update is not a
+fast forward. This does *not* attempt to merge <src> into <dst>. 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)
+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
@@ -218,6 +220,30 @@ 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::
+ Update the origin repository's master branch with the dev branch,
+ 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:
++
+----
+ 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 master
+----
++
+Commits A and B would no longer belong to a branch with a symbolic name,
+and so would be unreachable. As such, these commits would be removed by
+a `git gc` command on the origin repository.
+
Author
------
--
1.6.1.2.390.gba743
^ permalink raw reply related [flat|nested] 7+ messages in thread
* Re: [PATCH] Expand explanation of the use of + in git push refspecs.
2009-02-19 17:39 [PATCH] Expand explanation of the use of + in git push refspecs Marc Branchaud
2009-02-19 17:39 ` [PATCHv2] Docs: " Marc Branchaud
@ 2009-02-19 18:20 ` Sverre Rabbelier
2009-02-20 5:10 ` Junio C Hamano
2009-02-20 5:04 ` Junio C Hamano
2 siblings, 1 reply; 7+ messages in thread
From: Sverre Rabbelier @ 2009-02-19 18:20 UTC (permalink / raw)
To: Marc Branchaud; +Cc: git
On Thu, Feb 19, 2009 at 18:39, Marc Branchaud <marcnarc@xiplink.com> wrote:
> Documentation/git-push.txt | 40 ++++++++++++++++++++++++++++++++--------
> 1 files changed, 32 insertions(+), 8 deletions(-)
Most of this is under examples, so I don't think this is cluttering
the man page too much.
> +is recommended only for private, unshared repositories.) See EXAMPLES
I don't know about this line, I reckon Junio has a + refspec for the
pu branch, that is, it's ok to use a + refspec if you let others know
that the branch may be 'rebased'.
> + branch. *This can abandon commits in the origin repository.*
I liked your wording with the commits becoming dangling better.
> +That is, commits A and B would belong to an unreachable branch without a
> +symbolic name.
Perhaps it would be better to say those commits "would no longer
belong to a branch with a symbolic name, and thus become unreachable"?
--
Cheers,
Sverre Rabbelier
^ permalink raw reply [flat|nested] 7+ messages in thread
* Re: [PATCH] Expand explanation of the use of + in git push refspecs.
2009-02-19 17:39 [PATCH] Expand explanation of the use of + in git push refspecs Marc Branchaud
2009-02-19 17:39 ` [PATCHv2] Docs: " Marc Branchaud
2009-02-19 18:20 ` [PATCH] " Sverre Rabbelier
@ 2009-02-20 5:04 ` Junio C Hamano
2009-02-24 16:54 ` Marc Branchaud
2 siblings, 1 reply; 7+ messages in thread
From: Junio C Hamano @ 2009-02-20 5:04 UTC (permalink / raw)
To: Marc Branchaud; +Cc: git, srabbelier
Marc Branchaud <marcnarc@xiplink.com> writes:
> 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.
I am of two minds with this. The understanding of the concept of
fast-forwardness is necessary not just to understand push but also to
understand merge, and if glossary is missing the definition, we should add
one there. What exactly happens when the <dst> is updated is the same
regardless of ff or non-ff in that the old 40 hexdecimal object name is
gone and replaced with the new one, and it does not feel right to say "if
ff, we update if non-ff you can force to overwrite." Either way, you
overwrite and there is no trace of the old one. So we would want to say
something like:
The name of the object referenced by <src> is used to update the ref
<dst> on the remote side, but by default this is only allowed if the
update is fast-forward. By having the optional leading plus, you can
tell git to update the ref <dst> even when the update is not a
fast-forward.
> -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).
I think {plus} change is a good one, but rewording non-ff to overwrite is
not.
Please don't wrap a full paragraph, only to change a few sentences.
AsciiDoc wraps lines for output just fine; it took me a few extra minutes
to make sure there is no other changes.
^ permalink raw reply [flat|nested] 7+ messages in thread
* Re: [PATCH] Expand explanation of the use of + in git push refspecs.
2009-02-19 18:20 ` [PATCH] " Sverre Rabbelier
@ 2009-02-20 5:10 ` Junio C Hamano
0 siblings, 0 replies; 7+ messages in thread
From: Junio C Hamano @ 2009-02-20 5:10 UTC (permalink / raw)
To: Sverre Rabbelier; +Cc: Marc Branchaud, git
Sverre Rabbelier <srabbelier@gmail.com> writes:
>> + branch. *This can abandon commits in the origin repository.*
>
> I liked your wording with the commits becoming dangling better.
>
>> +That is, commits A and B would belong to an unreachable branch without a
>> +symbolic name.
>
> Perhaps it would be better to say those commits "would no longer
> belong to a branch with a symbolic name, and thus become unreachable"?
I agree with you on both counts.
^ permalink raw reply [flat|nested] 7+ messages in thread
* Re: [PATCH] Expand explanation of the use of + in git push refspecs.
2009-02-20 5:04 ` Junio C Hamano
@ 2009-02-24 16:54 ` Marc Branchaud
0 siblings, 0 replies; 7+ messages in thread
From: Marc Branchaud @ 2009-02-24 16:54 UTC (permalink / raw)
To: Junio C Hamano; +Cc: git, srabbelier
Junio C Hamano wrote:
>
> I am of two minds with this. The understanding of the concept of
> fast-forwardness is necessary not just to understand push but also to
> understand merge, and if glossary is missing the definition, we should add
> one there.
It's precisely because fast-forwarding and merging are so closely
related (at least in my mind) that I felt the need to clarify push's
documentation. My intuition about "non-fast-forward" is in the context
of pulling and merging. So the current man page sounds to me like
push's non-fast-forward is a merge, which it clearly isn't.
> What exactly happens when the <dst> is updated is the same
> regardless of ff or non-ff in that the old 40 hexdecimal object name is
> gone and replaced with the new one, and it does not feel right to say "if
> ff, we update if non-ff you can force to overwrite." Either way, you
> overwrite and there is no trace of the old one. So we would want to say
> something like:
>
> The name of the object referenced by <src> is used to update the ref
> <dst> on the remote side, but by default this is only allowed if the
> update is fast-forward. By having the optional leading plus, you can
> tell git to update the ref <dst> even when the update is not a
> fast-forward.
My second attempt used your wording (mostly), and also emphasized the
not-merging aspect.
> Please don't wrap a full paragraph, only to change a few sentences.
> AsciiDoc wraps lines for output just fine; it took me a few extra minutes
> to make sure there is no other changes.
Whoops, sorry! Will avoid reflowing in the future.
M.
^ permalink raw reply [flat|nested] 7+ messages in thread
* Re: [PATCHv2] Docs: Expand explanation of the use of + in git push refspecs.
2009-02-19 17:39 ` [PATCHv2] Docs: " Marc Branchaud
@ 2009-02-24 17:39 ` Junio C Hamano
0 siblings, 0 replies; 7+ messages in thread
From: Junio C Hamano @ 2009-02-24 17:39 UTC (permalink / raw)
To: Marc Branchaud; +Cc: git, srabbelier
Marc Branchaud <marcnarc@xiplink.com> writes:
> Signed-off-by: Marc Branchaud <marcnarc@xiplink.com>
> ---
>
> This version incorporates comments from Junio and Sverre.
>
> Documentation/git-push.txt | 36 +++++++++++++++++++++++++++++++-----
> 1 files changed, 31 insertions(+), 5 deletions(-)
Nice.
Looks much more readable than before, especially with a picture.
Thanks.
> diff --git a/Documentation/git-push.txt b/Documentation/git-push.txt
> index 7d1eced..2fae4fd 100644
> --- a/Documentation/git-push.txt
> +++ b/Documentation/git-push.txt
> @@ -48,17 +48,19 @@ 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.
> +
> -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.
> +The object referenced by <src> is used to update the <dst> reference
> +on the remote side, but by default this is only allowed if the
> +update can fast forward <dst>. By having the optional leading `{plus}`,
> +you can tell git to update the <dst> ref even when the update is not a
> +fast forward. This does *not* attempt to merge <src> into <dst>. 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)
> +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
> @@ -218,6 +220,30 @@ 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::
> + Update the origin repository's master branch with the dev branch,
> + 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:
> ++
> +----
> + 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 master
> +----
> ++
> +Commits A and B would no longer belong to a branch with a symbolic name,
> +and so would be unreachable. As such, these commits would be removed by
> +a `git gc` command on the origin repository.
> +
>
> Author
> ------
> --
> 1.6.1.2.390.gba743
^ permalink raw reply [flat|nested] 7+ messages in thread
end of thread, other threads:[~2009-02-24 17:41 UTC | newest]
Thread overview: 7+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2009-02-19 17:39 [PATCH] Expand explanation of the use of + in git push refspecs Marc Branchaud
2009-02-19 17:39 ` [PATCHv2] Docs: " Marc Branchaud
2009-02-24 17:39 ` Junio C Hamano
2009-02-19 18:20 ` [PATCH] " Sverre Rabbelier
2009-02-20 5:10 ` Junio C Hamano
2009-02-20 5:04 ` Junio C Hamano
2009-02-24 16:54 ` Marc Branchaud
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.