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

From: Kaartic Sivaraam <kaartic.sivaraam@gmail.com>
Date: Nov 16, 2017, 11:10 UTC
Message-ID: <493127ce-2596-fb93-993d-042097ca19bc@gmail.com>
In-Reply-To: <CAN0heSpUm=U7aGVtRoUoGZCvNsOZ04wLqTOx8kMvZEa8GQUiLQ@mail.gmail.com>

On Thursday 16 November 2017 04:19 PM, Martin Ågren wrote:

Show 14 quoted lines

> On 16 November 2017 at 08:46, Todd Zullinger <tmz@pobox.com> wrote:
>> diff --git a/Documentation/git-branch.txt b/Documentation/git-branch.txt
>> index d6587c5e96..159ca388f1 100644
>> --- a/Documentation/git-branch.txt
>> +++ b/Documentation/git-branch.txt
>> @@ -14,7 +14,7 @@ SYNOPSIS
>>          [(--merged | --no-merged) [<commit>]]
>>          [--contains [<commit]] [--no-contains [<commit>]]
>>          [--points-at <object>] [--format=<format>] [<pattern>...]
>> -'git branch' [--set-upstream | --track | --no-track] [-l] [-f] <branchname> [<start-point>]
>> +'git branch' [--track | --no-track] [-l] [-f] <branchname> [<start-point>]
> 
> Personally, I think this is an improvement.
>

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. 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.

Show 12 quoted lines

>>   'git branch' (--set-upstream-to=<upstream> | -u <upstream>) [<branchname>]
>>   'git branch' --unset-upstream [<branchname>]
>>   'git branch' (-m | -M) [<oldbranch>] <newbranch>
>> @@ -86,7 +86,7 @@ OPTIONS
>>   --delete::
>>          Delete a branch. The branch must be fully merged in its
>>          upstream branch, or in `HEAD` if no upstream was set with
>> -       `--track` or `--set-upstream`.
>> +       `--track` or `--set-upstream-to`.
> 
> Good catch.
>

Yep. Thanks for catching this.

--- Kaartic