From: Kaartic Sivaraam <kaartic.sivaraam@gmail.com>
Date: Thu, 16 Nov 2017 11:10:20 GMT
Subject: Re: [PATCH] branch doc: remove --set-upstream from synopsis
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:
> 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.


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