Re: [PATCH v2 4/4] branch: make "-l" a synonym for "--list"
From: Junio C Hamano <hidden>
Date: 2018-08-30 20:29:59
Jeff King [off-list ref] writes:
On Thu, Aug 30, 2018 at 09:53:25PM +0200, Ævar Arnfjörð Bjarmason wrote:quoted
quoted
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.
quoted
quoted
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.
quoted hunk
-- >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 <redacted> --- 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::