Ævar Arnfjörð Bjarmason <avarab@xxxxxxxxx> 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.
