{"thread":{"id":"47218","subject":"[PATCH] branch doc: remove --set-upstream from synopsis","startedAt":"2017-11-16T07:47:24Z","lastAt":"2017-11-17T03:02:58Z","messageCount":7,"participants":["Todd Zullinger","Martin Ågren","Kaartic Sivaraam","Junio C Hamano"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"332654","messageId":"20171116074643.19614-1-tmz@pobox.com","threadId":"47218","inReplyTo":null,"subject":"[PATCH] branch doc: remove --set-upstream from synopsis","fromName":"Todd Zullinger","fromEmail":"tmz@pobox.com","sentAt":"2017-11-16T07:46:43Z","receivedAt":"2017-11-16T07:47:24Z","isPatch":true,"sender":{"key":"tmz@pobox.com","avatar":"https://avatars.githubusercontent.com/u/806319?v=4"},"body":"Support for the --set-upstream option was removed in 52668846ea\n(builtin/branch: stop supporting the \"--set-upstream\" option,\n2017-08-17), after a long deprecation period.\n\nRemove the option from the command synopsis for consistency.  Replace\nanother reference to it in the description of `--delete` with\n`--set-upstream-to`.\n\nSigned-off-by: Todd Zullinger <tmz@pobox.com>\n---\n\nI noticed that --set-upstream was still in the synopsis for git branch.  I\ndon't think it was left there intentionally.  I looked through the thread where\nsupport for the option was removed and didn't notice any comments suggesting\notherwise[1].  With luck, I didn't miss the obvious while reading the thread.\n\n[1] https://public-inbox.org/git/20170807143938.5127-1-kaarticsivaraam91196@gmail.com/\n\n Documentation/git-branch.txt | 4 ++--\n 1 file changed, 2 insertions(+), 2 deletions(-)\n\ndiff --git a/Documentation/git-branch.txt b/Documentation/git-branch.txt\nindex d6587c5e96..159ca388f1 100644\n--- a/Documentation/git-branch.txt\n+++ b/Documentation/git-branch.txt\n@@ -14,7 +14,7 @@ SYNOPSIS\n \t[(--merged | --no-merged) [<commit>]]\n \t[--contains [<commit]] [--no-contains [<commit>]]\n \t[--points-at <object>] [--format=<format>] [<pattern>...]\n-'git branch' [--set-upstream | --track | --no-track] [-l] [-f] <branchname> [<start-point>]\n+'git branch' [--track | --no-track] [-l] [-f] <branchname> [<start-point>]\n 'git branch' (--set-upstream-to=<upstream> | -u <upstream>) [<branchname>]\n 'git branch' --unset-upstream [<branchname>]\n 'git branch' (-m | -M) [<oldbranch>] <newbranch>\n@@ -86,7 +86,7 @@ OPTIONS\n --delete::\n \tDelete a branch. The branch must be fully merged in its\n \tupstream branch, or in `HEAD` if no upstream was set with\n-\t`--track` or `--set-upstream`.\n+\t`--track` or `--set-upstream-to`.\n \n -D::\n \tShortcut for `--delete --force`.\n-- \n2.15.0\n\n"},{"id":"332658","messageId":"CAN0heSpUm=U7aGVtRoUoGZCvNsOZ04wLqTOx8kMvZEa8GQUiLQ@mail.gmail.com","threadId":"47218","inReplyTo":"20171116074643.19614-1-tmz@pobox.com","subject":"Re: [PATCH] branch doc: remove --set-upstream from synopsis","fromName":"Martin Ågren","fromEmail":"martin.agren@gmail.com","sentAt":"2017-11-16T10:49:33Z","receivedAt":"2017-11-16T10:49:39Z","isPatch":true,"sender":{"key":"martin.agren@gmail.com","avatar":null},"body":"On 16 November 2017 at 08:46, Todd Zullinger <tmz@pobox.com> wrote:\n> Support for the --set-upstream option was removed in 52668846ea\n> (builtin/branch: stop supporting the \"--set-upstream\" option,\n> 2017-08-17), after a long deprecation period.\n>\n> Remove the option from the command synopsis for consistency.  Replace\n> another reference to it in the description of `--delete` with\n> `--set-upstream-to`.\n>\n> Signed-off-by: Todd Zullinger <tmz@pobox.com>\n> ---\n>\n> I noticed that --set-upstream was still in the synopsis for git branch.  I\n> don't think it was left there intentionally.  I looked through the thread where\n> support for the option was removed and didn't notice any comments suggesting\n> otherwise[1].  With luck, I didn't miss the obvious while reading the thread.\n>\n> [1] https://public-inbox.org/git/20170807143938.5127-1-kaarticsivaraam91196@gmail.com/\n\nActually, the first version of the series did remove it from the\nsynopsis [2]. That hunk was later dropped. Kaartic mentioned it [3] and\nI thought out loud about it [4].\n\nI get the same initial thought now as then: It's a bit odd that we pique\nthe interest of the reader, but that when they try it out or read up on\nit, we say \"nope, this is not what you are looking for\".\n\n> diff --git a/Documentation/git-branch.txt b/Documentation/git-branch.txt\n> index d6587c5e96..159ca388f1 100644\n> --- a/Documentation/git-branch.txt\n> +++ b/Documentation/git-branch.txt\n> @@ -14,7 +14,7 @@ SYNOPSIS\n>         [(--merged | --no-merged) [<commit>]]\n>         [--contains [<commit]] [--no-contains [<commit>]]\n>         [--points-at <object>] [--format=<format>] [<pattern>...]\n> -'git branch' [--set-upstream | --track | --no-track] [-l] [-f] <branchname> [<start-point>]\n> +'git branch' [--track | --no-track] [-l] [-f] <branchname> [<start-point>]\n\nPersonally, I think this is an improvement.\n\n>  'git branch' (--set-upstream-to=<upstream> | -u <upstream>) [<branchname>]\n>  'git branch' --unset-upstream [<branchname>]\n>  'git branch' (-m | -M) [<oldbranch>] <newbranch>\n> @@ -86,7 +86,7 @@ OPTIONS\n>  --delete::\n>         Delete a branch. The branch must be fully merged in its\n>         upstream branch, or in `HEAD` if no upstream was set with\n> -       `--track` or `--set-upstream`.\n> +       `--track` or `--set-upstream-to`.\n\nGood catch.\n\nMartin\n\n[2] https://public-inbox.org/git/20170807143938.5127-2-kaarticsivaraam91196@gmail.com/\n\n[3] https://public-inbox.org/git/20170817025425.6647-2-kaarticsivaraam91196@gmail.com/\n\n[4] https://public-inbox.org/git/CAN0heSquaXk421sR6Ry59C+er8n26nC93=3KG1wD0xNXZkuiGw@mail.gmail.com/\n"},{"id":"332660","messageId":"493127ce-2596-fb93-993d-042097ca19bc@gmail.com","threadId":"47218","inReplyTo":"CAN0heSpUm=U7aGVtRoUoGZCvNsOZ04wLqTOx8kMvZEa8GQUiLQ@mail.gmail.com","subject":"Re: [PATCH] branch doc: remove --set-upstream from synopsis","fromName":"Kaartic Sivaraam","fromEmail":"kaartic.sivaraam@gmail.com","sentAt":"2017-11-16T11:10:20Z","receivedAt":"2017-11-16T11:10:34Z","isPatch":true,"sender":{"key":"kaartic.sivaraam@gmail.com","avatar":"https://avatars.githubusercontent.com/u/12448084?v=4"},"body":"On Thursday 16 November 2017 04:19 PM, Martin Ågren wrote:\n> On 16 November 2017 at 08:46, Todd Zullinger <tmz@pobox.com> wrote:\n>> diff --git a/Documentation/git-branch.txt b/Documentation/git-branch.txt\n>> index d6587c5e96..159ca388f1 100644\n>> --- a/Documentation/git-branch.txt\n>> +++ b/Documentation/git-branch.txt\n>> @@ -14,7 +14,7 @@ SYNOPSIS\n>>          [(--merged | --no-merged) [<commit>]]\n>>          [--contains [<commit]] [--no-contains [<commit>]]\n>>          [--points-at <object>] [--format=<format>] [<pattern>...]\n>> -'git branch' [--set-upstream | --track | --no-track] [-l] [-f] <branchname> [<start-point>]\n>> +'git branch' [--track | --no-track] [-l] [-f] <branchname> [<start-point>]\n> \n> Personally, I think this is an improvement.\n>\n\nI didn't remove it as there wasn't a \"strong\" consensus that this should \ngo off the \"Synopsis\" at that time. If removing it from the synopsis \nseems to be better than leaving it, then lets do it. Further, I think we \nshould make this some kind of \"guideline\" in this project to remain \nconsistent. Something like,\n\n\n     * If you deprecate an option of a command to an extent that it's not\n       usable at all, remove that option from the \"Synopsis\" of the\n       concerned \"Documentation\".\n\n\npossibly to \"Documentation/SubmittingPatches\" or at least keep this as \nsome form of undocumented guideline if this might make \n\"Documentation/SubmittingPatches\" unnecessarily clumsy. I dunno, was \njust thinking out loud.\n\n\n>>   'git branch' (--set-upstream-to=<upstream> | -u <upstream>) [<branchname>]\n>>   'git branch' --unset-upstream [<branchname>]\n>>   'git branch' (-m | -M) [<oldbranch>] <newbranch>\n>> @@ -86,7 +86,7 @@ OPTIONS\n>>   --delete::\n>>          Delete a branch. The branch must be fully merged in its\n>>          upstream branch, or in `HEAD` if no upstream was set with\n>> -       `--track` or `--set-upstream`.\n>> +       `--track` or `--set-upstream-to`.\n> \n> Good catch.\n> \n\nYep. Thanks for catching this.\n\n\n---\nKaartic\n"},{"id":"332673","messageId":"20171116170152.GD3693@zaya.teonanacatl.net","threadId":"47218","inReplyTo":"CAN0heSpUm=U7aGVtRoUoGZCvNsOZ04wLqTOx8kMvZEa8GQUiLQ@mail.gmail.com","subject":"Re: [PATCH] branch doc: remove --set-upstream from synopsis","fromName":"Todd Zullinger","fromEmail":"tmz@pobox.com","sentAt":"2017-11-16T17:01:52Z","receivedAt":"2017-11-16T17:02:03Z","isPatch":true,"sender":{"key":"tmz@pobox.com","avatar":"https://avatars.githubusercontent.com/u/806319?v=4"},"body":"Martin Ågren wrote:\n> On 16 November 2017 at 08:46, Todd Zullinger <tmz@pobox.com> wrote:\n>> I noticed that --set-upstream was still in the synopsis for git branch.  I \n>> don't think it was left there intentionally.  I looked through the thread where \n>> support for the option was removed and didn't notice any comments suggesting \n>> otherwise[1].  With luck, I didn't miss the obvious while reading the thread.\n>>\n>> [1] https://public-inbox.org/git/20170807143938.5127-1-kaarticsivaraam91196@gmail.com/\n>\n> Actually, the first version of the series did remove it from the \n> synopsis [2]. That hunk was later dropped. Kaartic mentioned it [3] and \n> I thought out loud about it [4].\n\nOh my.  I'll have to hope no prospective employer finds this thread if \nI ever apply for a job as a proofreader.  ;)\n\nThanks for pointing out the relevant parts of the discussion, of \ncourse.\n\n> I get the same initial thought now as then: It's a bit odd that we \n> pique the interest of the reader, but that when they try it out or \n> read up on it, we say \"nope, this is not what you are looking for\".\n\nIndeed.  If we do want to keep the option in the synopsis, it should \nat least be moved to the same entry as --set-upstream-to, since that's \nit's effect now.\n\nI don't think we should do that, but it would at least be accurate \nthere.  Using it like it's described in the synopsis now is an error.\n\n# git branch [--set-upstream | --track | --no-track] [-l] [-f] <branchname> [<start-point>]\n\n$ git branch --set-upstream mybranch master\nfatal: the '--set-upstream' option is no longer supported. Please use \n'--track' or '--set-upstream-to' instead.\n\n$ git branch --track mybranch master\nBranch 'mybranch' set up to track local branch 'master'.\n\nKaartic Sivaraam wrote:\n> I didn't remove it as there wasn't a \"strong\" consensus that this \n> should go off the \"Synopsis\" at that time. If removing it from the \n> synopsis seems to be better than leaving it, then lets do it.\n\nIndeed, I'm sorry I missed that you'd removed it earlier in the patch \nhistory.  I'm obviously in favor of removing it now. :)\n\n> Further, I think we should make this some kind of \"guideline\" in \n> this project to remain consistent. Something like,\n>\n>    * If you deprecate an option of a command to an extent that it's not \n>      usable at all, remove that option from the \"Synopsis\" of the \n>      concerned \"Documentation\".\n>\n> possibly to \"Documentation/SubmittingPatches\" or at least keep this as \n> some form of undocumented guideline if this might make \n> \"Documentation/SubmittingPatches\" unnecessarily clumsy. I dunno, was \n> just thinking out loud.\n\nYeah, it's probably tough to cover the many varied situations like \nthis to SubmittingPatches.  In general, I would agree with the above \nguideline.  It's best to not steer people toward options which we \nwould prefer them not to use.\n\nWhere that line falls with regard to documentation can certainly vary \na lot.  It's often hard for long-time git users to step into the shoes \nof new users who may be reading the documentation for the first time. \nThe right balance between enough information and not too much is \nalways tricky.\n\n[Incidentally, I ran into this because I had made some changes on a \nmaster branch of a repository.  Later, I wanted to move them to a \ntopic branch so I could do some other comparisons between master and \nupstream.  I wondered if I could setup the remote tracking using git \nbranch on the new branch in one step.  The recent branch --copy option \ndoes this perfectly (and easily).]\n\nThanks to both of you.\n\n-- \nTodd\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\nWhenever I feel blue, I start breathing again.\n\n"},{"id":"332732","messageId":"xmqqzi7lu2h8.fsf@gitster.mtv.corp.google.com","threadId":"47218","inReplyTo":"20171116074643.19614-1-tmz@pobox.com","subject":"Re: [PATCH] branch doc: remove --set-upstream from synopsis","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2017-11-17T01:18:43Z","receivedAt":"2017-11-17T01:18:49Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Todd Zullinger <tmz@pobox.com> writes:\n\n> Support for the --set-upstream option was removed in 52668846ea\n> (builtin/branch: stop supporting the \"--set-upstream\" option,\n> 2017-08-17), after a long deprecation period.\n>\n> Remove the option from the command synopsis for consistency.  Replace\n> another reference to it in the description of `--delete` with\n> `--set-upstream-to`.\n>\n> Signed-off-by: Todd Zullinger <tmz@pobox.com>\n> ---\n\nMakes sense.  Even though we internally still carry (and have to\ncarry) code to notice and explicitly reject \"--set-upstream\", I do\nnot think that we need to suggest its presence to the end user.\n\nThe option parsing code marks it with the PARSE_OPT_HIDDEN bit\ncorrectly and it would make sense to make the synopsis section\nfollow suit.\n\nThanks.\n"},{"id":"332734","messageId":"20171117013642.GL3693@zaya.teonanacatl.net","threadId":"47218","inReplyTo":"xmqqzi7lu2h8.fsf@gitster.mtv.corp.google.com","subject":"Re: [PATCH] branch doc: remove --set-upstream from synopsis","fromName":"Todd Zullinger","fromEmail":"tmz@pobox.com","sentAt":"2017-11-17T01:36:42Z","receivedAt":"2017-11-17T01:36:51Z","isPatch":true,"sender":{"key":"tmz@pobox.com","avatar":"https://avatars.githubusercontent.com/u/806319?v=4"},"body":"Junio C Hamano wrote:\n> Todd Zullinger <tmz@pobox.com> writes:\n>> Support for the --set-upstream option was removed in 52668846ea\n>> (builtin/branch: stop supporting the \"--set-upstream\" option,\n>> 2017-08-17), after a long deprecation period.\n>>\n>> Remove the option from the command synopsis for consistency.  Replace\n>> another reference to it in the description of `--delete` with\n>> `--set-upstream-to`.\n>>\n>> Signed-off-by: Todd Zullinger <tmz@pobox.com>\n>> ---\n>\n> Makes sense.  Even though we internally still carry (and have to\n> carry) code to notice and explicitly reject \"--set-upstream\", I do\n> not think that we need to suggest its presence to the end user.\n>\n> The option parsing code marks it with the PARSE_OPT_HIDDEN bit\n> correctly and it would make sense to make the synopsis section\n> follow suit.\n\nSeeing that the error output when using it tells the user to \"use\n'--track' or '--set-upstream-to' instead,\" should we perhaps also\nremove the --set-upstream entry entirely?  That's reads:\n\n    --set-upstream::\n            As this option had confusing syntax, it is no longer supported.\n            Please use `--track` or `--set-upstream-to` instead.\n\nI don't have a strong opinion either way, but perhaps the error\nmessage is all that's needed now?  Only users who have a long memory\nor are reading old documentation will call --set-upstream.  I can\nimagine someone coming along in a few months suggesting to remove the\nremaining reference to --set-upstream from the git branch\ndocumentation for consistency.\n\n-- \nTodd\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n...more people are driven insane through religious hysteria than by\ndrinking alcohol.\n    -- W.C. Fields\n\n"},{"id":"332739","messageId":"xmqq8tf5txno.fsf@gitster.mtv.corp.google.com","threadId":"47218","inReplyTo":"20171117013642.GL3693@zaya.teonanacatl.net","subject":"Re: [PATCH] branch doc: remove --set-upstream from synopsis","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2017-11-17T03:02:51Z","receivedAt":"2017-11-17T03:02:58Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Todd Zullinger <tmz@pobox.com> writes:\n\n> Seeing that the error output when using it tells the user to \"use\n> '--track' or '--set-upstream-to' instead,\" should we perhaps also\n> remove the --set-upstream entry entirely?  That's reads:\n>\n>    --set-upstream::\n>            As this option had confusing syntax, it is no longer supported.\n>            Please use `--track` or `--set-upstream-to` instead.\n>\n> I don't have a strong opinion either way, but perhaps the error\n> message is all that's needed now?  Only users who have a long memory\n> or are reading old documentation will call --set-upstream.  I can\n> imagine someone coming along in a few months suggesting to remove the\n> remaining reference to --set-upstream from the git branch\n> documentation for consistency.\n\nPerhaps.  But that must happen after we can safely remove the hidden\noption that is there only to issue an error message.  I suspect that\nwe may not quite ready yet (the entry is there to ensure that an\n\"branch --set-upstream $rest\" coming from an existing script and\ntrained fingers does not silently use --set-upstream-to thanks to\nthe helpful parse-options UI).\n"}]}