{"thread":{"id":"16085","subject":"[PATCH 1/7] Documentation: do not use regexp in refspec descriptions","startedAt":"2008-10-29T20:25:38Z","lastAt":"2008-11-02T20:13:21Z","messageCount":15,"participants":["Anders Melchiorsen","Daniel Barkalow","Junio C Hamano"],"isPatch":true,"patchVersion":1,"patchTotal":7},"messages":[{"id":"94219","messageId":"1225311945-17100-1-git-send-email-mail@cup.kalibalik.dk","threadId":"16085","inReplyTo":null,"subject":"Some updates to refspec documentation","fromName":"Anders Melchiorsen","fromEmail":"mail@cup.kalibalik.dk","sentAt":"2008-10-29T20:25:38Z","receivedAt":"2008-10-29T20:25:38Z","isPatch":false,"sender":{"key":"mail@cup.kalibalik.dk","avatar":null},"body":"\nI have skimmed the git-push manpage many times over a period of\nseveral months, without fully understanding it. Today I sat down and\nfigured it out. It took some experiments and a little reading of the\nsource.\n\nHere I offer some updates to the refspec documentation, so that others\ncan hopefully learn it faster than I did. As I expect some changes to\nbe more controversial than others, I have split it up in several small\nparts. Feel free to squash.\n\nThere is a risk that I have changed some things to be wrong. I wanted\nto make this update while I was still a frustrated newbie.\n\n\n\nAnders\n"},{"id":"94218","messageId":"1225311945-17100-2-git-send-email-mail@cup.kalibalik.dk","threadId":"16085","inReplyTo":"1225311945-17100-1-git-send-email-mail@cup.kalibalik.dk","subject":"[PATCH 1/7] Documentation: do not use regexp in refspec descriptions","fromName":"Anders Melchiorsen","fromEmail":"mail@cup.kalibalik.dk","sentAt":"2008-10-29T20:25:39Z","receivedAt":"2008-10-29T20:25:39Z","isPatch":true,"sender":{"key":"mail@cup.kalibalik.dk","avatar":null},"body":"The refspec format description was a mix of regexp and BNF, making it\nvery difficult to read.\n\nThe syntax is now easier to read, though wrong: all parts of the\nrefspec are actually optional.\n\nSigned-off-by: Anders Melchiorsen \n---\n Documentation/git-push.txt | 2 +-\n Documentation/pull-fetch-param.txt | 2 +-\n 2 files changed, 2 insertions(+), 2 deletions(-)\n\ndiff --git a/Documentation/git-push.txt b/Documentation/git-push.txt\nindex 6150b1b..df99c0b 100644\n--- a/Documentation/git-push.txt\n+++ b/Documentation/git-push.txt\n@@ -32,7 +32,7 @@ OPTIONS\n \n ...::\n \tThe canonical format of a parameter is\n-\t`+?:`; that is, an optional plus `{plus}`, followed\n+\t`[+]:`; that is, an optional plus `{plus}`, followed\n \tby the source ref, followed by a colon `:`, followed by\n \tthe destination ref.\n +\ndiff --git a/Documentation/pull-fetch-param.txt b/Documentation/pull-fetch-param.txt\nindex ebdd948..0ff1700 100644\n--- a/Documentation/pull-fetch-param.txt\n+++ b/Documentation/pull-fetch-param.txt\n@@ -6,7 +6,7 @@\n \n ::\n \tThe canonical format of a parameter is\n-\t`+?:`; that is, an optional plus `{plus}`, followed\n+\t`[+]:`; that is, an optional plus `{plus}`, followed\n \tby the source ref, followed by a colon `:`, followed by\n \tthe destination ref.\n +\n-- \n1.6.0.2.514.g23abd3\n"},{"id":"94224","messageId":"1225311945-17100-3-git-send-email-mail@cup.kalibalik.dk","threadId":"16085","inReplyTo":"1225311945-17100-2-git-send-email-mail@cup.kalibalik.dk","subject":"[PATCH 2/7] Documentation: git push repository can also be a remote","fromName":"Anders Melchiorsen","fromEmail":"mail@cup.kalibalik.dk","sentAt":"2008-10-29T20:25:40Z","receivedAt":"2008-10-29T20:25:40Z","isPatch":true,"sender":{"key":"mail@cup.kalibalik.dk","avatar":null},"body":"This is copied from pull-fetch-param.txt and helps the reader\nto not get stuck in the URL section.\n\nSigned-off-by: Anders Melchiorsen \n---\n Documentation/git-push.txt | 4 +++-\n 1 files changed, 3 insertions(+), 1 deletions(-)\n\ndiff --git a/Documentation/git-push.txt b/Documentation/git-push.txt\nindex df99c0b..02c7dae 100644\n--- a/Documentation/git-push.txt\n+++ b/Documentation/git-push.txt\n@@ -28,7 +28,9 @@ OPTIONS\n -------\n ::\n \tThe \"remote\" repository that is destination of a push\n-\toperation. See the section <> below.\n+\toperation. This parameter can be either a URL\n+\t(see the section <> below) or the name\n+\tof a remote (see the section <> below).\n \n ...::\n \tThe canonical format of a parameter is\n-- \n1.6.0.2.514.g23abd3\n"},{"id":"94221","messageId":"1225311945-17100-4-git-send-email-mail@cup.kalibalik.dk","threadId":"16085","inReplyTo":"1225311945-17100-3-git-send-email-mail@cup.kalibalik.dk","subject":"[PATCH 3/7] Documentation: rework SHA1 description in git push","fromName":"Anders Melchiorsen","fromEmail":"mail@cup.kalibalik.dk","sentAt":"2008-10-29T20:25:41Z","receivedAt":"2008-10-29T20:25:41Z","isPatch":true,"sender":{"key":"mail@cup.kalibalik.dk","avatar":null},"body":"Get rid of a double pair of parentheses. The arbitrary SHA1 is a\nspecial case, so it can be postponed a bit.\n\nAlso mention HEAD, which is possibly the most useful SHA1 in this\nsituation.\n\nMention that a SHA1 cannot be automatically matched to a .\n\nAdd HEAD as an example of an arbitrary SHA1.\n\nSigned-off-by: Anders Melchiorsen \n---\n Documentation/git-push.txt | 12 +++++++++---\n 1 files changed, 9 insertions(+), 3 deletions(-)\n\ndiff --git a/Documentation/git-push.txt b/Documentation/git-push.txt\nindex 02c7dae..fb9fb97 100644\n--- a/Documentation/git-push.txt\n+++ b/Documentation/git-push.txt\n@@ -38,9 +38,7 @@ OPTIONS\n \tby the source ref, followed by a colon `:`, followed by\n \tthe destination ref.\n +\n-The side represents the source branch (or arbitrary\n-\"SHA1 expression\", such as `master~4` (four parents before the\n-tip of `master` branch); see linkgit:git-rev-parse[1]) that you\n+The side represents the source branch that you\n want to push. The side represents the destination location.\n +\n The local ref that matches is used\n@@ -63,6 +61,10 @@ the local side, the remote side is updated if a head 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++\n+The can be an arbitrary \"SHA1 expression\", such as `HEAD`\n+or `master~4` (see linkgit:git-rev-parse[1]). In this case, a\n+ location has to be named.\n \n --all::\n \tInstead of naming each ref to push, specifies that all\n@@ -193,6 +195,10 @@ git push origin master::\n \twith it. If `master` did not exist remotely, it would be\n \tcreated.\n \n+git push origin HEAD:master::\n+\tPush the current head to the remote ref matching `master` in\n+\tthe `origin` repository.\n+\n 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-- \n1.6.0.2.514.g23abd3\n"},{"id":"94222","messageId":"1225311945-17100-5-git-send-email-mail@cup.kalibalik.dk","threadId":"16085","inReplyTo":"1225311945-17100-4-git-send-email-mail@cup.kalibalik.dk","subject":"[PATCH 4/7] Documentation: remove a redundant elaboration","fromName":"Anders Melchiorsen","fromEmail":"mail@cup.kalibalik.dk","sentAt":"2008-10-29T20:25:42Z","receivedAt":"2008-10-29T20:25:42Z","isPatch":true,"sender":{"key":"mail@cup.kalibalik.dk","avatar":null},"body":"The comment in parentheses is wrong, as one has to leave out both the\ncolon and . This situation is covered by the section a few lines\ndown:\n\n A parameter without a colon pushes the from the source\n repository to the destination repository under the same name.\n\nSo, just remove the parentheses.\n\nSigned-off-by: Anders Melchiorsen \n---\n Documentation/git-push.txt | 3 +--\n 1 files changed, 1 insertions(+), 2 deletions(-)\n\ndiff --git a/Documentation/git-push.txt b/Documentation/git-push.txt\nindex fb9fb97..9788d49 100644\n--- a/Documentation/git-push.txt\n+++ b/Documentation/git-push.txt\n@@ -42,8 +42,7 @@ The side represents the source branch that you\n want to push. The side represents the destination location.\n +\n The local ref that matches is used\n-to fast forward the remote ref that matches (or, if no was\n-specified, the same ref that referred to locally). If\n+to fast forward the remote ref that matches . If\n the optional leading plus `+` is used, the remote ref is updated\n even if it does not result in a fast forward update.\n +\n-- \n1.6.0.2.514.g23abd3\n"},{"id":"94225","messageId":"1225311945-17100-6-git-send-email-mail@cup.kalibalik.dk","threadId":"16085","inReplyTo":"1225311945-17100-5-git-send-email-mail@cup.kalibalik.dk","subject":"[PATCH 5/7] Documentation: elaborate on pushing tags","fromName":"Anders Melchiorsen","fromEmail":"mail@cup.kalibalik.dk","sentAt":"2008-10-29T20:25:43Z","receivedAt":"2008-10-29T20:25:43Z","isPatch":true,"sender":{"key":"mail@cup.kalibalik.dk","avatar":null},"body":"Make the description of pushing tags easier to read, but move the\nshorthand notation towards the end of the description. This gives\na better flow.\n\nSigned-off-by: Anders Melchiorsen \n---\n Documentation/git-push.txt | 8 +++++---\n 1 files changed, 5 insertions(+), 3 deletions(-)\n\ndiff --git a/Documentation/git-push.txt b/Documentation/git-push.txt\nindex 9788d49..52035db 100644\n--- a/Documentation/git-push.txt\n+++ b/Documentation/git-push.txt\n@@ -38,7 +38,7 @@ OPTIONS\n \tby the source ref, followed by a colon `:`, followed by\n \tthe destination ref.\n +\n-The side represents the source branch that you\n+The side represents the source branch or tag that you\n want to push. The side represents the destination location.\n +\n The local ref that matches is used\n@@ -46,8 +46,6 @@ to fast forward the remote ref that matches . If\n the optional leading plus `+` is used, the remote ref is updated\n even if it does not result in a fast forward update.\n +\n-`tag ` means the same as `refs/tags/:refs/tags/`.\n-+\n A parameter without a colon pushes the from the source\n repository to the destination repository under the same name.\n +\n@@ -64,6 +62,10 @@ nor in any Push line of the corresponding remotes file---see below).\n The can be an arbitrary \"SHA1 expression\", such as `HEAD`\n or `master~4` (see linkgit:git-rev-parse[1]). In this case, a\n location has to be named.\n++\n+When pushing tags, `tag ` can be used as a shorthand for\n+`refs/tags/:refs/tags/`. This should be specified as\n+two arguments (that is, without quotes in the shell).\n \n --all::\n \tInstead of naming each ref to push, specifies that all\n-- \n1.6.0.2.514.g23abd3\n"},{"id":"94220","messageId":"1225311945-17100-7-git-send-email-mail@cup.kalibalik.dk","threadId":"16085","inReplyTo":"1225311945-17100-6-git-send-email-mail@cup.kalibalik.dk","subject":"[PATCH 6/7] Documentation: mention branches rather than heads","fromName":"Anders Melchiorsen","fromEmail":"mail@cup.kalibalik.dk","sentAt":"2008-10-29T20:25:44Z","receivedAt":"2008-10-29T20:25:44Z","isPatch":true,"sender":{"key":"mail@cup.kalibalik.dk","avatar":null},"body":"Most of the git push page talks about branches, so make it consistent\nalso in this paragraph.\n\nSigned-off-by: Anders Melchiorsen \n---\n Documentation/git-push.txt | 4 ++--\n 1 files changed, 2 insertions(+), 2 deletions(-)\n\ndiff --git a/Documentation/git-push.txt b/Documentation/git-push.txt\nindex 52035db..4e339c7 100644\n--- a/Documentation/git-push.txt\n+++ b/Documentation/git-push.txt\n@@ -53,8 +53,8 @@ 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\" heads: for every head that exists on\n-the local side, the remote side is updated if a head of the same name\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-- \n1.6.0.2.514.g23abd3\n"},{"id":"94223","messageId":"1225311945-17100-8-git-send-email-mail@cup.kalibalik.dk","threadId":"16085","inReplyTo":"1225311945-17100-7-git-send-email-mail@cup.kalibalik.dk","subject":"[PATCH 7/7] Documentation: avoid using undefined parameters","fromName":"Anders Melchiorsen","fromEmail":"mail@cup.kalibalik.dk","sentAt":"2008-10-29T20:25:45Z","receivedAt":"2008-10-29T20:25:45Z","isPatch":true,"sender":{"key":"mail@cup.kalibalik.dk","avatar":null},"body":"The parameter has not been introduced, so rewrite to\navoid it.\n\nSigned-off-by: Anders Melchiorsen \n---\n Documentation/git-push.txt | 4 ++--\n 1 files changed, 2 insertions(+), 2 deletions(-)\n\ndiff --git a/Documentation/git-push.txt b/Documentation/git-push.txt\nindex 4e339c7..e848ff9 100644\n--- a/Documentation/git-push.txt\n+++ b/Documentation/git-push.txt\n@@ -46,8 +46,8 @@ to fast forward the remote ref that matches . If\n the optional leading plus `+` is used, the remote ref is updated\n even if it does not result in a fast forward update.\n +\n-A parameter without a colon pushes the from the source\n-repository to the destination repository under the same name.\n+A lonely parameter (without a colon and a destination) pushes\n+the to the same name in the destination repository.\n +\n Pushing an empty allows you to delete the ref from\n the remote repository.\n-- \n1.6.0.2.514.g23abd3\n"},{"id":"94228","messageId":"alpine.LNX.1.00.0810291638120.19665@iabervon.org","threadId":"16085","inReplyTo":"1225311945-17100-6-git-send-email-mail@cup.kalibalik.dk","subject":"Re: [PATCH 5/7] Documentation: elaborate on pushing tags","fromName":"Daniel Barkalow","fromEmail":"barkalow@iabervon.org","sentAt":"2008-10-29T20:40:16Z","receivedAt":"2008-10-29T20:40:16Z","isPatch":true,"sender":{"key":"barkalow@iabervon.org","avatar":"https://avatars.githubusercontent.com/u/55364219?v=4"},"body":"On Wed, 29 Oct 2008, Anders Melchiorsen wrote:\n\n> Make the description of pushing tags easier to read, but move the\n> shorthand notation towards the end of the description. This gives\n> a better flow.\n> \n> Signed-off-by: Anders Melchiorsen \n> ---\n> Documentation/git-push.txt | 8 +++++---\n> 1 files changed, 5 insertions(+), 3 deletions(-)\n> \n> diff --git a/Documentation/git-push.txt b/Documentation/git-push.txt\n> index 9788d49..52035db 100644\n> --- a/Documentation/git-push.txt\n> +++ b/Documentation/git-push.txt\n> @@ -38,7 +38,7 @@ OPTIONS\n> \tby the source ref, followed by a colon `:`, followed by\n> \tthe destination ref.\n> +\n> -The side represents the source branch that you\n> +The side represents the source branch or tag that you\n> want to push. The side represents the destination location.\n> +\n> The local ref that matches is used\n> @@ -46,8 +46,6 @@ to fast forward the remote ref that matches . If\n> the optional leading plus `+` is used, the remote ref is updated\n> even if it does not result in a fast forward update.\n> +\n> -`tag ` means the same as `refs/tags/:refs/tags/`.\n> -+\n> A parameter without a colon pushes the from the source\n> repository to the destination repository under the same name.\n> +\n> @@ -64,6 +62,10 @@ nor in any Push line of the corresponding remotes file---see below).\n> The can be an arbitrary \"SHA1 expression\", such as `HEAD`\n> or `master~4` (see linkgit:git-rev-parse[1]). In this case, a\n> location has to be named.\n> ++\n> +When pushing tags, `tag ` can be used as a shorthand for\n> +`refs/tags/:refs/tags/`. This should be specified as\n> +two arguments (that is, without quotes in the shell).\n\nI think this should be \"When pushing a tag, ...\", to avoid confusion with \n\"--tags\", which pushes (all) tags and doesn't need the \"tag \" \narguments.\n\n\t-Daniel\n*This .sig left intentionally blank*\n"},{"id":"94229","messageId":"878ws7b0d2.fsf@cup.kalibalik.dk","threadId":"16085","inReplyTo":"1225311945-17100-1-git-send-email-mail@cup.kalibalik.dk","subject":"Re: Some updates to refspec documentation","fromName":"Anders Melchiorsen","fromEmail":"mail@cup.kalibalik.dk","sentAt":"2008-10-29T20:41:13Z","receivedAt":"2008-10-29T20:41:13Z","isPatch":false,"sender":{"key":"mail@cup.kalibalik.dk","avatar":null},"body":"During my struggle, I also found a git push usability problem. The\nrefspec \":dst\" will delete the remote branch without warning.\n\nWhile this is indeed documented, you cannot blame somebody for\nthinking that a left out will default to HEAD, as it does for so\nmany other commands.\n\nIn a CVS-like setup, with everybody pushing to master, this could\ncause havoc.\n\nAs the \"git push :\" operation is destructive, I\nthink it should be protected by the -f option.\n\nFor the record, I did realize this before trying to push \":master\" :-).\n\n\n\nAnders.\n"},{"id":"94230","messageId":"874p2vb083.fsf@cup.kalibalik.dk","threadId":"16085","inReplyTo":"878ws7b0d2.fsf@cup.kalibalik.dk","subject":"Re: Some updates to refspec documentation","fromName":"Anders Melchiorsen","fromEmail":"mail@cup.kalibalik.dk","sentAt":"2008-10-29T20:44:12Z","receivedAt":"2008-10-29T20:44:12Z","isPatch":false,"sender":{"key":"mail@cup.kalibalik.dk","avatar":null},"body":"Anders Melchiorsen writes:\n\n> While this is indeed documented, you cannot blame somebody for\n> thinking that a left out will default to HEAD, as it does for\n> so many other commands.\n\nI actually think that defaulting to HEAD would be reasonable,\nbut it is probably less reasonable to change the meaning at this\npoint.\n\n\n\nAnders\n"},{"id":"94368","messageId":"7v7i7pba2x.fsf@gitster.siamese.dyndns.org","threadId":"16085","inReplyTo":"1225311945-17100-2-git-send-email-mail@cup.kalibalik.dk","subject":"Re: [PATCH 1/7] Documentation: do not use regexp in refspec descriptions","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2008-10-31T05:35:50Z","receivedAt":"2008-10-31T05:35:50Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Anders Melchiorsen writes:\n\n> The refspec format description was a mix of regexp and BNF, making it\n> very difficult to read.\n>\n> The syntax is now easier to read, though wrong: all parts of the\n> refspec are actually optional.\n\nIt probably is easier to read, but strictly speaking it is not wrong. The\ntwo parts, and , _always_ exist, even though either or both of\nthem can be an empty string.\n\n> diff --git a/Documentation/git-push.txt b/Documentation/git-push.txt\n> index 6150b1b..df99c0b 100644\n> --- a/Documentation/git-push.txt\n> +++ b/Documentation/git-push.txt\n> @@ -32,7 +32,7 @@ OPTIONS\n> \n> ...::\n> \tThe canonical format of a parameter is\n> -\t`+?:`; that is, an optional plus `{plus}`, followed\n> +\t`[+]:`; that is, an optional plus `{plus}`, followed\n> \tby the source ref, followed by a colon `:`, followed by\n> \tthe destination ref.\n\nI am wondering if it would be clearer and easier to understand if we just\nsaid:\n\n \tThe canonical format of a parameter is\n\tan optional plus `{plus}`, followed by the source ref,\n followed by a colon `:`, followed by the destination ref.\n\tFind various forms of refspecs in examples section.\n"},{"id":"94369","messageId":"7v1vxxba2c.fsf@gitster.siamese.dyndns.org","threadId":"16085","inReplyTo":"1225311945-17100-4-git-send-email-mail@cup.kalibalik.dk","subject":"Re: [PATCH 3/7] Documentation: rework SHA1 description in git push","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2008-10-31T05:36:11Z","receivedAt":"2008-10-31T05:36:11Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Anders Melchiorsen writes:\n\n> Get rid of a double pair of parentheses. The arbitrary SHA1 is a\n> special case, so it can be postponed a bit.\n\nHmmm...\n\nStrictly speaking, arbitrary SHA-1 is the general case, and branch name is\na special case of it, but in practice, branch name is the most frequently\nused form, and that is why it has the short-hand convention that allows it\nto to be pushed to the same name. I agree with the outcome of this patch\n(except for one point I'll mention shortly) because I think it is a good\nidea to talk about most frequently used form first, not because \"branch\"\nis the general case. IOW, the proposed commit log message is wrong.\n\n> Also mention HEAD, which is possibly the most useful SHA1 in this\n> situation.\n\nHEAD is indeed useful, but it falls into the special case of \"branch\nname\", not \"arbitrary SHA-1 expression\". This distinction is important\nbecause you can push \"HEAD\" without colon and it will act as if you said\nmaster:master (or whatever branch you are currently on). This is already\ndescribed in the existing doc:\n\n The local ref that matches is used\n to fast forward the remote ref that matches (or, if no was\n specified, the same ref that referred to locally).\n\nbut I agree that it is unnecessarily hard to understand, because the\ndocument tries to describe the general case first and then relies on the\nuser to understand that \"ref referred to locally\" means \"branch\nname\". We should make this part more explicit.\n\nWith that in mind, I have two paragraphs to replace the parts your patch\ntouches as a counterproposal.\n\n> diff --git a/Documentation/git-push.txt b/Documentation/git-push.txt\n> index 02c7dae..fb9fb97 100644\n> --- a/Documentation/git-push.txt\n> +++ b/Documentation/git-push.txt\n> @@ -38,9 +38,7 @@ OPTIONS\n> \tby the source ref, followed by a colon `:`, followed by\n> \tthe destination ref.\n> +\n> -The side represents the source branch (or arbitrary\n> -\"SHA1 expression\", such as `master~4` (four parents before the\n> -tip of `master` branch); see linkgit:git-rev-parse[1]) that you\n> +The side represents the source branch that you\n> want to push. The side represents the destination location.\n\nThe is often the name of the branch you would want to push, but it\ncan be any arbitrary \"SHA-1 expression\", such as `master~4` (four parents\nbefore the tip of `master` branch -- see linkgit:git-rev-parse[1]), or\n`HEAD` (the tip of the current branch). The tells which ref on the\nremote side is updated with this push.\n\nThe object referenced by is used to fast forward the ref on\nthe remote side. You can omit to update the same ref on the remote\nside as ( is often the name of a branch you push, and often you\npush to the same branch on the remote side; `git push HEAD` is a handy way\nto push only the current branch to the remote side under the same name).\nIf the optional leading plus `{plus}` is used, the remote ref is updated\neven if it does not result in a fast forward update.\n\n> @@ -193,6 +195,10 @@ git push origin master::\n> \twith it. If `master` did not exist remotely, it would be\n> \tcreated.\n> \n> +git push origin HEAD:master::\n> +\tPush the current head to the remote ref matching `master` in\n> +\tthe `origin` repository.\n> +\n\nAdditional example is good, but you would want to tell readers that this\nwould be useful when your current branch is _not_ 'master'.\n"},{"id":"94671","messageId":"877i7mnjh3.fsf@cup.kalibalik.dk","threadId":"16085","inReplyTo":"7v7i7pba2x.fsf@gitster.siamese.dyndns.org","subject":"Re: [PATCH 1/7] Documentation: do not use regexp in refspec descriptions","fromName":"Anders Melchiorsen","fromEmail":"mail@cup.kalibalik.dk","sentAt":"2008-11-02T17:08:56Z","receivedAt":"2008-11-02T17:08:56Z","isPatch":true,"sender":{"key":"mail@cup.kalibalik.dk","avatar":null},"body":"Junio C Hamano writes:\n\n> Anders Melchiorsen writes:\n>\n>> The syntax is now easier to read, though wrong: all parts of the\n>> refspec are actually optional.\n>\n> It probably is easier to read, but strictly speaking it is not\n> wrong. The two parts, and , _always_ exist, even though\n> either or both of them can be an empty string.\n\nThe colon is not required, though the format suggests that it is.\n\n\n>> ...::\n>> \tThe canonical format of a parameter is\n>> -\t`+?:`; that is, an optional plus `{plus}`, followed\n>> +\t`[+]:`; that is, an optional plus `{plus}`, followed\n>> \tby the source ref, followed by a colon `:`, followed by\n>> \tthe destination ref.\n>\n> I am wondering if it would be clearer and easier to understand if we just\n> said:\n>\n> \tThe canonical format of a parameter is\n> \tan optional plus `{plus}`, followed by the source ref,\n> followed by a colon `:`, followed by the destination ref.\n> \tFind various forms of refspecs in examples section.\n\nI think that is an improvement. Removing the word \"canonical\" would be\neven better, IMHO.\n\n\nAnders.\n"},{"id":"94688","messageId":"873ai9opi6.fsf@cup.kalibalik.dk","threadId":"16085","inReplyTo":"7v1vxxba2c.fsf@gitster.siamese.dyndns.org","subject":"Re: [PATCH 3/7] Documentation: rework SHA1 description in git push","fromName":"Anders Melchiorsen","fromEmail":"mail@cup.kalibalik.dk","sentAt":"2008-11-02T20:13:21Z","receivedAt":"2008-11-02T20:13:21Z","isPatch":true,"sender":{"key":"mail@cup.kalibalik.dk","avatar":null},"body":"Junio C Hamano writes:\n\n> Anders Melchiorsen writes:\n>\n>> Get rid of a double pair of parentheses. The arbitrary SHA1 is a\n>> special case, so it can be postponed a bit.\n>\n> Hmmm...\n>\n> Strictly speaking, arbitrary SHA-1 is the general case, and branch name is\n> a special case of it, but in practice, branch name is the most frequently\n> used form, and that is why it has the short-hand convention that allows it\n> to to be pushed to the same name.\n\nRight, that was poor wording. When I said \"special case\", I meant it\nas \"rare use case\".\n\n\n>> Also mention HEAD, which is possibly the most useful SHA1 in this\n>> situation.\n>\n> HEAD is indeed useful, but it falls into the special case of \"branch\n> name\", not \"arbitrary SHA-1 expression\". This distinction is important\n> because you can push \"HEAD\" without colon and it will act as if you said\n> master:master (or whatever branch you are currently on). This is already\n> described in the existing doc:\n>\n> The local ref that matches is used\n> to fast forward the remote ref that matches (or, if no was\n> specified, the same ref that referred to locally).\n\nOh, I did (obviously) not realize that you can use HEAD in that way,\nand actually I cannot read that from the quoted paragraph even now\nthat I know about it.\n\nIt seems to me that HEAD is a special-special case, and that it is not\neven mentioned in the current documentation. With my current\nunderstanding, I would say that HEAD can work both as a \"branch name\"\n(that discovers its own name automatically) and as an \"arbitrary\nSHA-1\" (with a detached head).\n\n\n>> --- a/Documentation/git-push.txt\n>> +++ b/Documentation/git-push.txt\n>> @@ -38,9 +38,7 @@ OPTIONS\n>> \tby the source ref, followed by a colon `:`, followed by\n>> \tthe destination ref.\n>> +\n>> -The side represents the source branch (or arbitrary\n>> -\"SHA1 expression\", such as `master~4` (four parents before the\n>> -tip of `master` branch); see linkgit:git-rev-parse[1]) that you\n>> +The side represents the source branch that you\n>> want to push. The side represents the destination location.\n>\n> The is often the name of the branch you would want to push, but it\n> can be any arbitrary \"SHA-1 expression\", such as `master~4` (four parents\n> before the tip of `master` branch -- see linkgit:git-rev-parse[1]), or\n> `HEAD` (the tip of the current branch). The tells which ref on the\n> remote side is updated with this push.\n>\n> The object referenced by is used to fast forward the ref on\n> the remote side. You can omit to update the same ref on the remote\n> side as ( is often the name of a branch you push, and often you\n> push to the same branch on the remote side; `git push HEAD` is a handy way\n> to push only the current branch to the remote side under the same name).\n> If the optional leading plus `{plus}` is used, the remote ref is updated\n> even if it does not result in a fast forward update.\n\nI find those paragraphs hard to read. The shorter sentences and lack\nof parentheses in my patch series was more to my taste. I actually\nthink that the examples, like explaining master~4, detracts from the\nmain topic and makes it harder to find the information.\n\n\n\n>> @@ -193,6 +195,10 @@ git push origin master::\n>> \twith it. If `master` did not exist remotely, it would be\n>> \tcreated.\n>> \n>> +git push origin HEAD:master::\n>> +\tPush the current head to the remote ref matching `master` in\n>> +\tthe `origin` repository.\n>> +\n>\n> Additional example is good, but you would want to tell readers that this\n> would be useful when your current branch is _not_ 'master'.\n\nRight.\n\n\n\nCheers,\nAnders.\n"}]}