Martin Ågren wrote:
On 16 November 2017 at 08:46, Todd Zullinger <tmz@xxxxxxxxx> wrote:
I noticed that --set-upstream was still in the synopsis for git branch. I
don't think it was left there intentionally. I looked through the thread where
support for the option was removed and didn't notice any comments suggesting
otherwise[1]. With luck, I didn't miss the obvious while reading the thread.
[1] https://public-inbox.org/git/20170807143938.5127-1-kaarticsivaraam91196@xxxxxxxxx/
Actually, the first version of the series did remove it from the
synopsis [2]. That hunk was later dropped. Kaartic mentioned it [3] and
I thought out loud about it [4].
Oh my. I'll have to hope no prospective employer finds this thread if
I ever apply for a job as a proofreader. ;)
Thanks for pointing out the relevant parts of the discussion, of
course.
I get the same initial thought now as then: It's a bit odd that we
pique the interest of the reader, but that when they try it out or
read up on it, we say "nope, this is not what you are looking for".
Indeed. If we do want to keep the option in the synopsis, it should
at least be moved to the same entry as --set-upstream-to, since that's
it's effect now.
I don't think we should do that, but it would at least be accurate
there. Using it like it's described in the synopsis now is an error.
# git branch [--set-upstream | --track | --no-track] [-l] [-f] <branchname> [<start-point>]
$ git branch --set-upstream mybranch master
fatal: the '--set-upstream' option is no longer supported. Please use
'--track' or '--set-upstream-to' instead.
$ git branch --track mybranch master
Branch 'mybranch' set up to track local branch 'master'.
Kaartic Sivaraam wrote:
I didn't remove it as there wasn't a "strong" consensus that this
should go off the "Synopsis" at that time. If removing it from the
synopsis seems to be better than leaving it, then lets do it.
Indeed, I'm sorry I missed that you'd removed it earlier in the patch
history. I'm obviously in favor of removing it now. :)
Further, I think we should make this some kind of "guideline" in
this project to remain consistent. Something like,
* If you deprecate an option of a command to an extent that it's not
usable at all, remove that option from the "Synopsis" of the
concerned "Documentation".
possibly to "Documentation/SubmittingPatches" or at least keep this as
some form of undocumented guideline if this might make
"Documentation/SubmittingPatches" unnecessarily clumsy. I dunno, was
just thinking out loud.
Yeah, it's probably tough to cover the many varied situations like
this to SubmittingPatches. In general, I would agree with the above
guideline. It's best to not steer people toward options which we
would prefer them not to use.
Where that line falls with regard to documentation can certainly vary
a lot. It's often hard for long-time git users to step into the shoes
of new users who may be reading the documentation for the first time.
The right balance between enough information and not too much is
always tricky.
[Incidentally, I ran into this because I had made some changes on a
master branch of a repository. Later, I wanted to move them to a
topic branch so I could do some other comparisons between master and
upstream. I wondered if I could setup the remote tracking using git
branch on the new branch in one step. The recent branch --copy option
does this perfectly (and easily).]
Thanks to both of you.
--
Todd
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Whenever I feel blue, I start breathing again.
