[RFC] checkout: add synonym of -b

Commit Message

Mikkel Kjeldsen Nov. 3, 2018, 7:18 p.m. UTC

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 <[e-mail]>
---

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


base-commit: d582ea202b626dcc6c3b01e1e11a296d9badd730

Comments

Junio C Hamano Nov. 5, 2018, 12:41 a.m. UTC | #1

Mikkel Kjeldsen <[e-mail]> writes:

> 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 <[e-mail]>
> ---
>
> 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.

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.

Patch

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