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.
