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

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

On Fri, Jun 22 2018, Jeff King wrote:

> diff --git a/Documentation/git-branch.txt b/Documentation/git-branch.txt
> index 1072ca0eb6..fc88e984e1 100644
> --- a/Documentation/git-branch.txt
> +++ b/Documentation/git-branch.txt
> @@ -100,8 +100,6 @@ OPTIONS
>  	The negated form `--no-create-reflog` only overrides an earlier
>  	`--create-reflog`, but currently does not negate the setting of
>  	`core.logAllRefUpdates`.
> -+
> -The `-l` option is a deprecated synonym for `--create-reflog`.
>
>  -f::
>  --force::
> @@ -156,6 +154,7 @@ This option is only applicable in non-verbose mode.
>  --all::
>  	List both remote-tracking branches and local branches.
>
> +-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.

     -v::
     -vv::

We're about to release 2.19 with the deprecation (but it still means
--create-reflog), this patch is sitting in next.

Similarly to your 2/4 we'll have some scripts in the wild using -l,
let's at least give them a headsup that this changed in the docs, as
well as anyone on >=2.20 (or whenever we plan to merge this down from
next) a warning that if they're writing some script they can't rely on
`-l` for older clients.