From: Junio C Hamano <gitster@pobox.com>
Date: Thu, 30 Aug 2018 20:29:53 GMT
Subject: Re: [PATCH v2 4/4] branch: make "-l" a synonym for "--list"
Message-ID: <xmqqo9dj4mym.fsf@gitster-ct.c.googlers.com>
In-Reply-To: <20180830200452.GB22407@sigill.intra.peff.net>

Jeff King <peff@peff.net> 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@peff.net>
> ---
>  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::