Jeff King <peff@xxxxxxxx> writes:
> On Thu, Aug 30, 2018 at 09:53:25PM +0200, Ævar Arnfjörð Bjarmason wrote:
>
>> > 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!
>
> Sorry, this is my fault. Patch is below (which would go on top of
> jk/branch-l-1-repurpose).
Heh, reviewers who did not notice share the same blame. The patch
looks good. Thanks for a quick update.
>> > 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.
>
> I don't have a strong opinion either way. If we do mention it, it should
> probably be short ("Until Git v2.20, the `-l` option was a synonym for
> `--create-reflog").
I agree that the short one would of course be good. I am on the
fence about mentioning the warning only given in 2.19.
> -- >8 --
> Subject: [PATCH] doc/git-branch: remove obsolete "-l" references
>
> The previous commit switched "-l" to meaning "--list", but a
> few vestiges of its prior meaning as "--create-reflog"
> remained:
>
> - the synopsis mentioned "-l" when creating a new branch;
> we can drop this entirely, as it has been the default
> for years
>
> - the --list command mentions the unfortunate "-l"
> confusion, but we've now fixed that
>
> Signed-off-by: Jeff King <peff@xxxxxxxx>
> ---
> Documentation/git-branch.txt | 6 +-----
> 1 file changed, 1 insertion(+), 5 deletions(-)
>
> diff --git a/Documentation/git-branch.txt b/Documentation/git-branch.txt
> index 5552dfcec3..bf5316ffa9 100644
> --- a/Documentation/git-branch.txt
> +++ b/Documentation/git-branch.txt
> @@ -14,7 +14,7 @@ SYNOPSIS
> [(--merged | --no-merged) [<commit>]]
> [--contains [<commit]] [--no-contains [<commit>]]
> [--points-at <object>] [--format=<format>] [<pattern>...]
> -'git branch' [--track | --no-track] [-l] [-f] <branchname> [<start-point>]
> +'git branch' [--track | --no-track] [-f] <branchname> [<start-point>]
> 'git branch' (--set-upstream-to=<upstream> | -u <upstream>) [<branchname>]
> 'git branch' --unset-upstream [<branchname>]
> 'git branch' (-m | -M) [<oldbranch>] <newbranch>
> @@ -159,10 +159,6 @@ This option is only applicable in non-verbose mode.
> List branches. With optional `<pattern>...`, e.g. `git
> branch --list 'maint-*'`, list only the branches that match
> the pattern(s).
> -+
> -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.
>
> -v::
> -vv::
