Re: [PATCH] branch doc: Change `git branch <pattern>` to use `<branchname>`

["Ævar Arnfjörð Bjarmason" <avarab@gmail.com>]

On Thu, Mar 23, 2017 at 6:01 PM, Junio C Hamano <gitster@pobox.com> wrote:
> Ævar Arnfjörð Bjarmason  <avarab@gmail.com> writes:
>
>> Change an example for `git branch <pattern>` to say `git branch
>> <branchname>` to be consistent with the synopsis. This changes
>> documentation added in d8d33736b5 ("branch: allow pattern arguments",
>> 2011-08-28).
>>
>> Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
>> ---
>>  Documentation/git-branch.txt | 2 +-
>>  1 file changed, 1 insertion(+), 1 deletion(-)
>>
>> diff --git a/Documentation/git-branch.txt b/Documentation/git-branch.txt
>> index 092f1bcf9f..e65e5c0dee 100644
>> --- a/Documentation/git-branch.txt
>> +++ b/Documentation/git-branch.txt
>> @@ -142,7 +142,7 @@ This option is only applicable in non-verbose mode.
>>       List both remote-tracking branches and local branches.
>>
>>  --list::
>> -     Activate the list mode. `git branch <pattern>` would try to create a branch,
>> +     Activate the list mode. `git branch <branchname>` would try to create a branch,
>>       use `git branch --list <pattern>` to list matching branches.
>
> This makes the description more correct.
>
> I am not sure if it makes that much sense to have that sentence here
> in the first place (after all, it is describing a behaviour of a
> mode that is *not* the list mode), but I guess that it may be a
> common mistake to forget to specify "-l" while asking for branches
> that match the pattern?  If we were writing this today from scratch,
> I would perhaps write something entirely different, e.g.

I'm just doing s/pattern/branchname/ on the existing documentation. If
you'd like to entirely reword this to make that unnecessary that
sounds good, but makes sense that you then submit that patch & just
drop this one, rather than me copy/pasting your proposal, sending that
as my own patch etc...

>         --list::
>                 List branches.  With optional <pattern>... at the
>                 end of the command line, list only the branches that
>                 match any of the given patterns.  Do not forget '-l'
>                 and say "git branch <pattern>", as it will instead
>                 try to create a new branch whose name is <pattern>,
>                 which is a common mistake.

I like the old one better. It has 3 actual command examples you can
readily see. This turns that into more prose that requires the reader
to mentally parse most of it and mentally insert the mentioned command
line switches into the equivalent of those 3 examples we just provided
before.

> though.
>
> Thanks.