On Thu, Aug 30 2018, Junio C Hamano wrote: > Æ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. 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.
