[PATCH] Expand explanation of the use of + in git push refspecs.

[PATCH] Expand explanation of the use of + in git push refspecs.

[Marc Branchaud]

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

[PATCHv2] Docs: Expand explanation of the use of + in git push refspecs.

[Marc Branchaud]

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

Re: [PATCHv2] Docs: Expand explanation of the use of + in git push refspecs.

[Junio C Hamano]

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

Re: [PATCH] Expand explanation of the use of + in git push refspecs.

[Sverre Rabbelier]

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

Re: [PATCH] Expand explanation of the use of + in git push refspecs.

[Junio C Hamano]

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.

Re: [PATCH] Expand explanation of the use of + in git push refspecs.

[Junio C Hamano]

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.

Re: [PATCH] Expand explanation of the use of + in git push refspecs.

[Marc Branchaud]

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.