Re: [PATCH v2 4/4] branch: make "-l" a synonym for "--list"

[Junio C Hamano <gitster@pobox.com>]

Ævar Arnfjörð Bjarmason <avarab@gmail.com> writes:

>> +-l::
>>  --list::
>>  	List branches.  With optional `<pattern>...`, e.g. `git
>>  	branch --list 'maint-*'`, list only the branches that match
>
> I think it's better to have something like this on top:
>
>     diff --git a/Documentation/git-branch.txt b/Documentation/git-branch.txt
>     index 5552dfcec3..a03cb1ebc9 100644
>     --- a/Documentation/git-branch.txt
>     +++ b/Documentation/git-branch.txt
>     @@ -163,6 +163,11 @@ This option is only applicable in non-verbose mode.
>      This should not be confused with `git branch -l <branchname>`,
>      which creates a branch named `<branchname>` with a reflog.
>      See `--create-reflog` above for details.
>     ++
>     +
>     +Until Git version 2.20 `-l` was the short form of
>     +`--create-reflog`. As of version 2.19 using it would warn about a
>     +future deprecation.

Doesn't your patch show a more grave issue with the current state of
'next'?

The sentence in the pre-context in your suggested patch says that
"--list" should not be confused with "git branch -l <branchname>",
but --list and -l are now synonyms in the new world order.

Worse yet, '-l' is no longer a way to create the branch with a
reflog; in the new world, you would say "--create-reflog" if you
want to do so.  "git branch -l foo" would list branches that match
that pattern 'foo'.

In the SYNOPSIS section we still see "[-l]" listed; that also must
be replaced with "--create-reflog", or just dropped, as that is the
default.

I do not know if the documentation that is shipped in 2.20 should
talk about how the old world looked like, though.  `-l` was a short
for `--create-reflog` is worth saying, but I do not see much value
in talking about the warning given in 2.19.

Thanks.