{"thread":{"id":"17903","subject":"[PATCH] Expand explanation of the use of + in git push refspecs.","startedAt":"2009-02-19T17:39:47Z","lastAt":"2009-02-24T17:39:42Z","messageCount":7,"participants":["Marc Branchaud","Sverre Rabbelier","Junio C Hamano"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"105489","messageId":"20090219180258.2C7983360A6@rincewind","threadId":"17903","inReplyTo":null,"subject":"[PATCH] Expand explanation of the use of + in git push refspecs.","fromName":"Marc Branchaud","fromEmail":"marcnarc@xiplink.com","sentAt":"2009-02-19T17:39:47Z","receivedAt":"2009-02-19T17:39:47Z","isPatch":true,"sender":{"key":"marcnarc@xiplink.com","avatar":"https://avatars.githubusercontent.com/u/14980203?v=4"},"body":"Signed-off-by: Marc Branchaud \n---\n Documentation/git-push.txt | 40 ++++++++++++++++++++++++++++++++--------\n 1 files changed, 32 insertions(+), 8 deletions(-)\n\ndiff --git a/Documentation/git-push.txt b/Documentation/git-push.txt\nindex 7d1eced..4cb13a1 100644\n--- a/Documentation/git-push.txt\n+++ b/Documentation/git-push.txt\n@@ -50,20 +50,21 @@ updated.\n +\n The object referenced by is used to fast forward the ref \n on the remote side. If the optional leading plus `{plus}` is used, the\n-remote ref is updated even if it does not result in a fast forward\n-update.\n+remote ref is *overwritten* with the local ref. (The use of `{plus}`\n+is recommended only for private, unshared repositories.) See EXAMPLES\n+below for details.\n +\n `tag ` means the same as `refs/tags/:refs/tags/`.\n +\n Pushing an empty allows you to delete the ref from\n the remote repository.\n +\n-The special refspec `:` (or `+:` to allow non-fast forward updates)\n-directs git to push \"matching\" branches: for every branch that exists on\n-the local side, the remote side is updated if a branch of the same name\n-already exists on the remote side. This is the default operation mode\n-if no explicit refspec is found (that is neither on the command line\n-nor in any Push line of the corresponding remotes file---see below).\n+The special refspec `:` (or `{plus}:` to allow overwriting) directs git to\n+push \"matching\" branches: for every branch that exists on the local\n+side, the remote side is updated if a branch of the same name already\n+exists on the remote side. This is the default operation mode if no\n+explicit refspec is found (that is neither on the command line nor in\n+any Push line of the corresponding remotes file---see below).\n \n --all::\n \tInstead of naming each ref to push, specifies that all\n@@ -218,6 +219,29 @@ git push origin :experimental::\n \tFind a ref that matches `experimental` in the `origin` repository\n \t(e.g. `refs/heads/experimental`), and delete it.\n \n+git push origin {plus}dev:master::\n+\t*Overwrite* the origin repository's master branch with the dev\n+\tbranch. *This can abandon commits in the origin repository.*\n+\tConsider the following situation:\n++\n+----\n+\t o---o---o---A---B origin/master\n+\t \\\n+\t X---Y---Z dev\n+----\n++\n+The above command would change the origin repository to\n++\n+----\n+\t A---B (unnamed branch)\n+\t /\n+\t o---o---o---X---Y---Z origin/master\n+----\n++\n+That is, commits A and B would belong to an unreachable branch without a\n+symbolic name. As such, these commits would be removed by a `git gc`\n+command on the origin repository.\n+\n \n Author\n ------\n-- \n1.6.1.2.390.gba743\n"},{"id":"106075","messageId":"20090224165105.0FAE53360A6@rincewind","threadId":"17903","inReplyTo":"20090219180258.2C7983360A6@rincewind","subject":"[PATCHv2] Docs: Expand explanation of the use of + in git push refspecs.","fromName":"Marc Branchaud","fromEmail":"marcnarc@xiplink.com","sentAt":"2009-02-19T17:39:47Z","receivedAt":"2009-02-19T17:39:47Z","isPatch":false,"sender":{"key":"marcnarc@xiplink.com","avatar":"https://avatars.githubusercontent.com/u/14980203?v=4"},"body":"Signed-off-by: Marc Branchaud \n---\n\nThis version incorporates comments from Junio and Sverre.\n\n Documentation/git-push.txt | 36 +++++++++++++++++++++++++++++++-----\n 1 files changed, 31 insertions(+), 5 deletions(-)\n\ndiff --git a/Documentation/git-push.txt b/Documentation/git-push.txt\nindex 7d1eced..2fae4fd 100644\n--- a/Documentation/git-push.txt\n+++ b/Documentation/git-push.txt\n@@ -48,17 +48,19 @@ push. Arbitrary expressions cannot be used here, an actual ref must\n be named. If `:` is omitted, the same ref as will be\n updated.\n +\n-The object referenced by is used to fast forward the ref \n-on the remote side. If the optional leading plus `{plus}` is used, the\n-remote ref is updated even if it does not result in a fast forward\n-update.\n+The object referenced by is used to update the reference\n+on the remote side, but by default this is only allowed if the\n+update can fast forward . By having the optional leading `{plus}`,\n+you can tell git to update the ref even when the update is not a\n+fast forward. This does *not* attempt to merge into . See\n+EXAMPLES below for details.\n +\n `tag ` means the same as `refs/tags/:refs/tags/`.\n +\n Pushing an empty allows you to delete the ref from\n the remote repository.\n +\n-The special refspec `:` (or `+:` to allow non-fast forward updates)\n+The special refspec `:` (or `{plus}:` to allow non-fast forward updates)\n directs git to push \"matching\" branches: for every branch that exists on\n the local side, the remote side is updated if a branch of the same name\n already exists on the remote side. This is the default operation mode\n@@ -218,6 +220,30 @@ git push origin :experimental::\n \tFind a ref that matches `experimental` in the `origin` repository\n \t(e.g. `refs/heads/experimental`), and delete it.\n \n+git push origin {plus}dev:master::\n+\tUpdate the origin repository's master branch with the dev branch,\n+\tallowing non-fast forward updates. *This can leave unreferenced\n+\tcommits dangling in the origin repository.* Consider the\n+\tfollowing situation, where a fast forward is not possible:\n++\n+----\n+\t o---o---o---A---B origin/master\n+\t \\\n+\t X---Y---Z dev\n+----\n++\n+The above command would change the origin repository to\n++\n+----\n+\t A---B (unnamed branch)\n+\t /\n+\t o---o---o---X---Y---Z master\n+----\n++\n+Commits A and B would no longer belong to a branch with a symbolic name,\n+and so would be unreachable. As such, these commits would be removed by\n+a `git gc` command on the origin repository.\n+\n \n Author\n ------\n-- \n1.6.1.2.390.gba743\n"},{"id":"105491","messageId":"bd6139dc0902191020i787e56a7tbe88cedfc2cb4028@mail.gmail.com","threadId":"17903","inReplyTo":"20090219180258.2C7983360A6@rincewind","subject":"Re: [PATCH] Expand explanation of the use of + in git push refspecs.","fromName":"Sverre Rabbelier","fromEmail":"srabbelier@gmail.com","sentAt":"2009-02-19T18:20:15Z","receivedAt":"2009-02-19T18:20:15Z","isPatch":true,"sender":{"key":"srabbelier@gmail.com","avatar":"https://avatars.githubusercontent.com/u/3098?v=4"},"body":"On Thu, Feb 19, 2009 at 18:39, Marc Branchaud wrote:\n> Documentation/git-push.txt | 40 ++++++++++++++++++++++++++++++++--------\n> 1 files changed, 32 insertions(+), 8 deletions(-)\n\nMost of this is under examples, so I don't think this is cluttering\nthe man page too much.\n\n> +is recommended only for private, unshared repositories.) See EXAMPLES\n\nI don't know about this line, I reckon Junio has a + refspec for the\npu branch, that is, it's ok to use a + refspec if you let others know\nthat the branch may be 'rebased'.\n\n> + branch. *This can abandon commits in the origin repository.*\n\nI liked your wording with the commits becoming dangling better.\n\n\n> +That is, commits A and B would belong to an unreachable branch without a\n> +symbolic name.\n\nPerhaps it would be better to say those commits \"would no longer\nbelong to a branch with a symbolic name, and thus become unreachable\"?\n\n-- \nCheers,\n\nSverre Rabbelier\n"},{"id":"105554","messageId":"7viqn5k8c4.fsf@gitster.siamese.dyndns.org","threadId":"17903","inReplyTo":"20090219180258.2C7983360A6@rincewind","subject":"Re: [PATCH] Expand explanation of the use of + in git push refspecs.","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2009-02-20T05:04:11Z","receivedAt":"2009-02-20T05:04:11Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Marc Branchaud writes:\n\n> Signed-off-by: Marc Branchaud \n> ---\n> Documentation/git-push.txt | 40 ++++++++++++++++++++++++++++++++--------\n> 1 files changed, 32 insertions(+), 8 deletions(-)\n>\n> diff --git a/Documentation/git-push.txt b/Documentation/git-push.txt\n> index 7d1eced..4cb13a1 100644\n> --- a/Documentation/git-push.txt\n> +++ b/Documentation/git-push.txt\n> @@ -50,20 +50,21 @@ updated.\n> +\n> The object referenced by is used to fast forward the ref \n> on the remote side. If the optional leading plus `{plus}` is used, the\n> -remote ref is updated even if it does not result in a fast forward\n> -update.\n> +remote ref is *overwritten* with the local ref. (The use of `{plus}`\n> +is recommended only for private, unshared repositories.) See EXAMPLES\n> +below for details.\n\nI am of two minds with this. The understanding of the concept of\nfast-forwardness is necessary not just to understand push but also to\nunderstand merge, and if glossary is missing the definition, we should add\none there. What exactly happens when the is updated is the same\nregardless of ff or non-ff in that the old 40 hexdecimal object name is\ngone and replaced with the new one, and it does not feel right to say \"if\nff, we update if non-ff you can force to overwrite.\" Either way, you\noverwrite and there is no trace of the old one. So we would want to say\nsomething like:\n\n The name of the object referenced by is used to update the ref\n on the remote side, but by default this is only allowed if the\n update is fast-forward. By having the optional leading plus, you can\n tell git to update the ref even when the update is not a\n fast-forward.\n\n> -The special refspec `:` (or `+:` to allow non-fast forward updates)\n> -directs git to push \"matching\" branches: for every branch that exists on\n> -the local side, the remote side is updated if a branch of the same name\n> -already exists on the remote side. This is the default operation mode\n> -if no explicit refspec is found (that is neither on the command line\n> -nor in any Push line of the corresponding remotes file---see below).\n> +The special refspec `:` (or `{plus}:` to allow overwriting) directs git to\n> +push \"matching\" branches: for every branch that exists on the local\n> +side, the remote side is updated if a branch of the same name already\n> +exists on the remote side. This is the default operation mode if no\n> +explicit refspec is found (that is neither on the command line nor in\n> +any Push line of the corresponding remotes file---see below).\n\nI think {plus} change is a good one, but rewording non-ff to overwrite is\nnot.\n\nPlease don't wrap a full paragraph, only to change a few sentences.\nAsciiDoc wraps lines for output just fine; it took me a few extra minutes\nto make sure there is no other changes.\n"},{"id":"105555","messageId":"7veixtk814.fsf@gitster.siamese.dyndns.org","threadId":"17903","inReplyTo":"bd6139dc0902191020i787e56a7tbe88cedfc2cb4028@mail.gmail.com","subject":"Re: [PATCH] Expand explanation of the use of + in git push refspecs.","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2009-02-20T05:10:47Z","receivedAt":"2009-02-20T05:10:47Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Sverre Rabbelier writes:\n\n>> + branch. *This can abandon commits in the origin repository.*\n>\n> I liked your wording with the commits becoming dangling better.\n>\n>> +That is, commits A and B would belong to an unreachable branch without a\n>> +symbolic name.\n>\n> Perhaps it would be better to say those commits \"would no longer\n> belong to a branch with a symbolic name, and thus become unreachable\"?\n\nI agree with you on both counts.\n"},{"id":"106076","messageId":"49A42655.40708@xiplink.com","threadId":"17903","inReplyTo":"7viqn5k8c4.fsf@gitster.siamese.dyndns.org","subject":"Re: [PATCH] Expand explanation of the use of + in git push refspecs.","fromName":"Marc Branchaud","fromEmail":"marcnarc@xiplink.com","sentAt":"2009-02-24T16:54:45Z","receivedAt":"2009-02-24T16:54:45Z","isPatch":true,"sender":{"key":"marcnarc@xiplink.com","avatar":"https://avatars.githubusercontent.com/u/14980203?v=4"},"body":"Junio C Hamano wrote:\n> \n> I am of two minds with this. The understanding of the concept of\n> fast-forwardness is necessary not just to understand push but also to\n> understand merge, and if glossary is missing the definition, we should add\n> one there.\n\nIt's precisely because fast-forwarding and merging are so closely \nrelated (at least in my mind) that I felt the need to clarify push's \ndocumentation. My intuition about \"non-fast-forward\" is in the context \nof pulling and merging. So the current man page sounds to me like \npush's non-fast-forward is a merge, which it clearly isn't.\n\n> What exactly happens when the is updated is the same\n> regardless of ff or non-ff in that the old 40 hexdecimal object name is\n> gone and replaced with the new one, and it does not feel right to say \"if\n> ff, we update if non-ff you can force to overwrite.\" Either way, you\n> overwrite and there is no trace of the old one. So we would want to say\n> something like:\n> \n> The name of the object referenced by is used to update the ref\n> on the remote side, but by default this is only allowed if the\n> update is fast-forward. By having the optional leading plus, you can\n> tell git to update the ref even when the update is not a\n> fast-forward.\n\nMy second attempt used your wording (mostly), and also emphasized the \nnot-merging aspect.\n\n> Please don't wrap a full paragraph, only to change a few sentences.\n> AsciiDoc wraps lines for output just fine; it took me a few extra minutes\n> to make sure there is no other changes.\n\nWhoops, sorry! Will avoid reflowing in the future.\n\n\t\tM.\n"},{"id":"106085","messageId":"7veixnhgyp.fsf@gitster.siamese.dyndns.org","threadId":"17903","inReplyTo":"20090224165105.0FAE53360A6@rincewind","subject":"Re: [PATCHv2] Docs: Expand explanation of the use of + in git push refspecs.","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2009-02-24T17:39:42Z","receivedAt":"2009-02-24T17:39:42Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Marc Branchaud writes:\n\n> Signed-off-by: Marc Branchaud \n> ---\n>\n> This version incorporates comments from Junio and Sverre.\n>\n> Documentation/git-push.txt | 36 +++++++++++++++++++++++++++++++-----\n> 1 files changed, 31 insertions(+), 5 deletions(-)\n\nNice.\n\nLooks much more readable than before, especially with a picture.\n\nThanks.\n\n> diff --git a/Documentation/git-push.txt b/Documentation/git-push.txt\n> index 7d1eced..2fae4fd 100644\n> --- a/Documentation/git-push.txt\n> +++ b/Documentation/git-push.txt\n> @@ -48,17 +48,19 @@ push. Arbitrary expressions cannot be used here, an actual ref must\n> be named. If `:` is omitted, the same ref as will be\n> updated.\n> +\n> -The object referenced by is used to fast forward the ref \n> -on the remote side. If the optional leading plus `{plus}` is used, the\n> -remote ref is updated even if it does not result in a fast forward\n> -update.\n> +The object referenced by is used to update the reference\n> +on the remote side, but by default this is only allowed if the\n> +update can fast forward . By having the optional leading `{plus}`,\n> +you can tell git to update the ref even when the update is not a\n> +fast forward. This does *not* attempt to merge into . See\n> +EXAMPLES below for details.\n> +\n> `tag ` means the same as `refs/tags/:refs/tags/`.\n> +\n> Pushing an empty allows you to delete the ref from\n> the remote repository.\n> +\n> -The special refspec `:` (or `+:` to allow non-fast forward updates)\n> +The special refspec `:` (or `{plus}:` to allow non-fast forward updates)\n> directs git to push \"matching\" branches: for every branch that exists on\n> the local side, the remote side is updated if a branch of the same name\n> already exists on the remote side. This is the default operation mode\n> @@ -218,6 +220,30 @@ git push origin :experimental::\n> \tFind a ref that matches `experimental` in the `origin` repository\n> \t(e.g. `refs/heads/experimental`), and delete it.\n> \n> +git push origin {plus}dev:master::\n> +\tUpdate the origin repository's master branch with the dev branch,\n> +\tallowing non-fast forward updates. *This can leave unreferenced\n> +\tcommits dangling in the origin repository.* Consider the\n> +\tfollowing situation, where a fast forward is not possible:\n> ++\n> +----\n> +\t o---o---o---A---B origin/master\n> +\t \\\n> +\t X---Y---Z dev\n> +----\n> ++\n> +The above command would change the origin repository to\n> ++\n> +----\n> +\t A---B (unnamed branch)\n> +\t /\n> +\t o---o---o---X---Y---Z master\n> +----\n> ++\n> +Commits A and B would no longer belong to a branch with a symbolic name,\n> +and so would be unreachable. As such, these commits would be removed by\n> +a `git gc` command on the origin repository.\n> +\n> \n> Author\n> ------\n> -- \n> 1.6.1.2.390.gba743\n"}]}