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

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

On Thu, Aug 30 2018, Junio C Hamano wrote:

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

Oh yes, it seems all of the doc indeed wasn't updated!

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

I'm anticipating that there will be users in the wild with similar -l
invocations, noting this helps them, because they'll be wondering what
some script that does "git branch -l <name>" is trying to do while
reading our docs.

Both our command-line options (plumbing or otherwise) and file various
formats (e.g. I had a similar mention of version differences in my
recent skipList patches) can be expected to be used across multiple git
versions, by users who most likely are only browsing the latest version
of the docs, not comparing how the manpage looked like in multiple git
versions to see if an option meant something different, or if a format
was documented as behaving differently.