path: root/Documentation/git-branch.txt
diff options
authorJeff King <>2018-06-22 09:24:14 (GMT)
committerJunio C Hamano <>2018-06-22 20:19:33 (GMT)
commit055930bc8960c303ece01d9a34740f25a2a6bba6 (patch)
tree1513fb77c51654c3301dc375aae554f9903c253d /Documentation/git-branch.txt
parent7687f19e939dd8c9a2a67ede31b019092f0a1ccf (diff)
branch: deprecate "-l" option
The "-l" option is short for "--create-reflog". This has caused much confusion over the years. Most people expect it to work as "--list", because that would match the other "mode" options like -d/--delete and -m/--move, as well as the similar -l/--list option of git-tag. Adding to the confusion, using "-l" _appears_ to work as "--list" in some cases: $ git branch -l * master because the branch command defaults to listing (so even trying to specify --list in the command above is redundant). But that may bite the user later when they add a pattern, like: $ git branch -l foo which does not return an empty list, but in fact creates a new branch (with a reflog, naturally) called "foo". It's also probably quite uncommon for people to actually use "-l" to create a reflog. Since 0bee591869 (Enable reflogs by default in any repository with a working directory., 2006-12-14), this is the default in non-bare repositories. So it's rather unfortunate that the feature squats on the short-and-sweet "-l" (which was only added in 3a4b3f269c (Create/delete branch ref logs., 2006-05-19), meaning there were only 7 months where it was actually useful). Let's deprecate "-l" in hopes of eventually re-purposing it to "--list". Note that we issue the warning only when we're not in list mode. This means that people for whom it works as a happy accident, namely: $ git branch -l master won't see the warning at all. And when we eventually switch to it meaning "--list", that will just continue to work. We do the issue the warning for these important cases: - when we are actually creating a branch, in case the user really did mean it as "--create-reflog" - when we are in some _other_ mode, like deletion. There the "-l" is a noop for now, but it will eventually conflict with any other mode request, and the user should be told that this is changing. Signed-off-by: Jeff King <> Signed-off-by: Junio C Hamano <>
Diffstat (limited to 'Documentation/git-branch.txt')
1 files changed, 2 insertions, 1 deletions
diff --git a/Documentation/git-branch.txt b/Documentation/git-branch.txt
index 02eccbb..1072ca0 100644
--- a/Documentation/git-branch.txt
+++ b/Documentation/git-branch.txt
@@ -91,7 +91,6 @@ OPTIONS
Shortcut for `--delete --force`.
Create the branch's reflog. This activates recording of
all changes made to the branch ref, enabling use of date
@@ -101,6 +100,8 @@ OPTIONS
The negated form `--no-create-reflog` only overrides an earlier
`--create-reflog`, but currently does not negate the setting of
+The `-l` option is a deprecated synonym for `--create-reflog`.