[RFC PATCH] checkout: add synonym of -b

[Mikkel Kjeldsen <commonquail@gmail.com>]

Add --new-branch as a long-form synonym of -b. I occasionally encounter
some confusion in new users having interpreted "checkout -b" to mean
"checkout branch", or internalized it as "the way to create a new
branch" rather than merely a convenience for "branch && checkout". I
think an explicit long-form can help alleviate that.

Signed-off-by: Mikkel Kjeldsen <commonquail@gmail.com>
---

Notes:
    This makes the synopsis and description lines look a little clumsy (and
    I think incorrect...?) so if this proposal is accepted perhaps those
    parts are better left out. It is meant more for training and
    documentation than regular usage, anyway.
    
    I thought I had seen something like "--create-branch" in use by another
    command and had intended to use that but I can no longer find that and
    so went with "--new-branch" named after the option's argument.
    
    There does not seem to be a practice for testing short- versus long-form
    arguments so I did not include one, but I'd be happy to.

 Documentation/git-checkout.txt | 5 +++--
 builtin/checkout.c             | 2 +-
 t/t9902-completion.sh          | 1 +
 3 files changed, 5 insertions(+), 3 deletions(-)

diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt
index 801de2f764..7651d8b83d 100644
--- a/Documentation/git-checkout.txt
+++ b/Documentation/git-checkout.txt
@@ -11,7 +11,7 @@ SYNOPSIS
 'git checkout' [-q] [-f] [-m] [<branch>]
 'git checkout' [-q] [-f] [-m] --detach [<branch>]
 'git checkout' [-q] [-f] [-m] [--detach] <commit>
-'git checkout' [-q] [-f] [-m] [[-b|-B|--orphan] <new_branch>] [<start_point>]
+'git checkout' [-q] [-f] [-m] [[(-b|--new-branch)|-B|--orphan] <new_branch>] [<start_point>]
 'git checkout' [-f|--ours|--theirs|-m|--conflict=<style>] [<tree-ish>] [--] <paths>...
 'git checkout' [<tree-ish>] [--] <pathspec>...
 'git checkout' (-p|--patch) [<tree-ish>] [--] [<paths>...]
@@ -52,7 +52,7 @@ You could omit <branch>, in which case the command degenerates to
 rather expensive side-effects to show only the tracking information,
 if exists, for the current branch.
 
-'git checkout' -b|-B <new_branch> [<start point>]::
+'git checkout' (-b|--new-branch)|-B <new_branch> [<start point>]::
 
 	Specifying `-b` causes a new branch to be created as if
 	linkgit:git-branch[1] were called and then checked out.  In
@@ -154,6 +154,7 @@ on your side branch as `theirs` (i.e. "one contributor's work on top
 of it").
 
 -b <new_branch>::
+--new-branch=<new_branch>::
 	Create a new branch named <new_branch> and start it at
 	<start_point>; see linkgit:git-branch[1] for details.
 
diff --git a/builtin/checkout.c b/builtin/checkout.c
index acdafc6e4c..4a27d94a86 100644
--- a/builtin/checkout.c
+++ b/builtin/checkout.c
@@ -1232,7 +1232,7 @@ int cmd_checkout(int argc, const char **argv, const char *prefix)
 	int dwim_remotes_matched = 0;
 	struct option options[] = {
 		OPT__QUIET(&opts.quiet, N_("suppress progress reporting")),
-		OPT_STRING('b', NULL, &opts.new_branch, N_("branch"),
+		OPT_STRING('b', "new-branch", &opts.new_branch, N_("branch"),
 			   N_("create and checkout a new branch")),
 		OPT_STRING('B', NULL, &opts.new_branch_force, N_("branch"),
 			   N_("create/reset and checkout a branch")),
diff --git a/t/t9902-completion.sh b/t/t9902-completion.sh
index 175f83d704..00614fdcc5 100755
--- a/t/t9902-completion.sh
+++ b/t/t9902-completion.sh
@@ -1428,6 +1428,7 @@ test_expect_success 'double dash "git checkout"' '
 	--ours Z
 	--theirs Z
 	--merge Z
+	--new-branch=Z
 	--conflict=Z
 	--patch Z
 	--ignore-skip-worktree-bits Z

base-commit: d582ea202b626dcc6c3b01e1e11a296d9badd730
-- 
2.19.1