Re: [PATCH v2 4/4] branch: make "-l" a synonym for "--list"

From: Jeff King <peff@peff.net>
Date: Aug 30, 2018, 20:04 UTC
Message-ID: <20180830200452.GB22407@sigill.intra.peff.net>
In-Reply-To: <87in3rd422.fsf@evledraar.gmail.com>

On Thu, Aug 30, 2018 at 09:53:25PM +0200, Ævar Arnfjörð Bjarmason wrote:

Show 5 quoted lines

> > 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).

Show 9 quoted lines

> > 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").

-Peff

-- >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::

-- 
2.19.0.rc1.546.g3fcb3c0d7c