Re: [PATCH] branch doc: remove --set-upstream from synopsis

From: Todd Zullinger <tmz@pobox.com>
Date: Nov 17, 2017, 01:36 UTC
Message-ID: <20171117013642.GL3693@zaya.teonanacatl.net>
In-Reply-To: <xmqqzi7lu2h8.fsf@gitster.mtv.corp.google.com>

Junio C Hamano wrote:

Show 19 quoted lines

> Todd Zullinger <tmz@pobox.com> writes:
>> Support for the --set-upstream option was removed in 52668846ea
>> (builtin/branch: stop supporting the "--set-upstream" option,
>> 2017-08-17), after a long deprecation period.
>>
>> Remove the option from the command synopsis for consistency.  Replace
>> another reference to it in the description of `--delete` with
>> `--set-upstream-to`.
>>
>> Signed-off-by: Todd Zullinger <tmz@pobox.com>
>> ---
>
> Makes sense.  Even though we internally still carry (and have to
> carry) code to notice and explicitly reject "--set-upstream", I do
> not think that we need to suggest its presence to the end user.
>
> The option parsing code marks it with the PARSE_OPT_HIDDEN bit
> correctly and it would make sense to make the synopsis section
> follow suit.

Seeing that the error output when using it tells the user to "use '--track' or '--set-upstream-to' instead," should we perhaps also remove the --set-upstream entry entirely? That's reads:

    --set-upstream::
            As this option had confusing syntax, it is no longer supported.
            Please use `--track` or `--set-upstream-to` instead.

I don't have a strong opinion either way, but perhaps the error message is all that's needed now? Only users who have a long memory or are reading old documentation will call --set-upstream. I can imagine someone coming along in a few months suggesting to remove the remaining reference to --set-upstream from the git branch documentation for consistency.

-- 
Todd
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
...more people are driven insane through religious hysteria than by
drinking alcohol.
    -- W.C. Fields