checkout: add synonym of -b

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.

---

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

index 801de2f764..7651d8b83d 100644
@@ -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.
 

index acdafc6e4c..4a27d94a86 100644
@@ -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")),

index 175f83d704..00614fdcc5 100755
@@ -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

Sounds like even you (who wrote this patch) expect the long form option to be impractical for regular usage and everybody would end up using the -b form?

I am borderline "Meh" on this change, slightly on the negative side, primarily because we'd need to worry about what to do with "-B" if we did this to "-b", and I do not think it is worth even spending brain cycles to worry about it (e.g. should it be --force-new-branch? should --new-branch used together with --force a better-looking alternative? if we were to add --force, how should it interact with other existing options the command support? etc.)

But let's hear what others think.

Thanks.