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

Todd Zullinger [off-list ref] writes:

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.

Perhaps.  But that must happen after we can safely remove the hidden
option that is there only to issue an error message.  I suspect that
we may not quite ready yet (the entry is there to ensure that an
"branch --set-upstream $rest" coming from an existing script and
trained fingers does not silently use --set-upstream-to thanks to
the helpful parse-options UI).