checkout: print something when checking out paths

Since the purpose of printing this is to help disambiguate. Only do it when "--" is missing (the actual reason though is many tests check empty stderr to see that no error is raised and I'm too lazy to fix all the test cases).

Quoted 4 lines · Nguyễn Thái Ngọc Duy

Since the purpose of printing this is to help disambiguate. Only do it when "--" is missing (the actual reason though is many tests check empty stderr to see that no error is raised and I'm too lazy to fix all the test cases).

Heh, honesty is good but in this particular case the official reason alone would make perfect sense, too ;-)

As with progress output, shouldn't this automatically be turned off when the standard error stream goes to non tty, as the real purpose of printing is to help the user sitting in front of the terminal and interacting with the command?

And by this, I do not mean to say that "When -- is missing" can go away. I agree that "--" is a clear sign that the user knows what s/he is doing---to overwrite the paths in the working tree that match the pathspec.

builtin/checkout.c static int checkout_paths(const struct checkout_opts *opts, · line 379

Quoted 8 lines

builtin/checkout.c +2 -1

@@ -371,17 +374,27 @@ static int checkout_paths(const struct checkout_opts *opts,
              struct cache_entry *ce = active_cache[pos];
              if (ce->ce_flags & CE_MATCHED) {
                      if (!ce_stage(ce)) {
-                             errs |= checkout_entry(ce, &state, NULL);
+                             errs |= checkout_entry(ce, &state,
+                                                    NULL, &nr_checkouts);
                              continue;

As we count inside checkout_entry(), we might not actually write this out when we know that the working tree file is up to date already but we do not increment in that case either, so we keep track of the accurate count of "updates", not path matches (i.e. we are not reporting "we made sure this many paths are up to date in the working tree"; instead we are reporting how many paths we needed to overwrite in the working tree).

builtin/checkout.c static int checkout_paths(const struct checkout_opts *opts, · line 397

Quoted 11 lines

builtin/checkout.c +7 -1

                      pos = skip_same_name(ce, pos) - 1;
              }
      }
-     errs |= finish_delayed_checkout(&state);
+     errs |= finish_delayed_checkout(&state, &nr_checkouts);
+
+     if (opts->count_checkout_paths)
+             fprintf_ln(stderr, Q_("%d path has been updated",
+                                   "%d paths have been updated",
+                                   nr_checkouts),
+                        nr_checkouts);

This one may want to be protected behind isatty(2). Or the default value of count_checkout_paths could be tweakedbased on isatty(2).

Another thing I'm going to change (if this v1 is in the right direction): print different messages for "git checkout -- foo" and "git checkout foo -- bar". The first one is "%d paths have been reverted" but the second one does different things and probably should say "%d paths have been updated from branch foo" or something like that.

One of the problems with "git checkout" is that it does so many different things and could confuse people specially when we fail to handle ambiguation correctly.

Quoted 3 lines · Nguyễn Thái Ngọc Duy

One of the problems with "git checkout" is that it does so many different things and could confuse people specially when we fail to handle ambiguation correctly.

You would have realized that this is way too noisy if you ran "make test", which may have spewed something like this on the screen.

[19:09:19] t4120-apply-popt.sh ................................ ok 1624 ms ( 0.26 usr 0.21 sys + 5.31 cusr 3.51 csys = 9.29 CPU)
[19:09:20] t9164-git-svn-dcommit-concurrent.sh ................ skipped: Perl SVN libraries not found or unusable
[19:09:20] t1310-config-default.sh ............................ ok 177 ms ( 0.07 usr 0.01 sys + 0.89 cusr 0.66 csys = 1.63 CPU)
===( 20175;154 1297/? 155/? 6/? 3/3 2/? 4/? 4/? 3/? 5... )===Checked out 1 path out of the index
Checked out 1 path out of the index
Checked out 1 path out of the index
Checked out 1 path out of the index
Checked out 1 path out of the index

[19:09:20] t1408-packed-refs.sh ............................... ok      310 ms ( 0.06 usr  0.00 sys +  0.69 cusr  0.52 csys =  1.27 CPU)
[19:09:20] t0025-crlf-renormalize.sh .......................... ok      246 ms ( 0.03 usr  0.01 sys +  0.34 cusr  0.22 csys =  0.60 CPU)

I am very tempted to suggest to treat this as a training wheel and enable only when checkout.showpathcount is set to true, or something like that.

Quoted 8 lines · Junio C Hamano

Quoted 4 lines · Nguyễn Thái Ngọc Duy

Since the purpose of printing this is to help disambiguate. Only do it when "--" is missing (the actual reason though is many tests check empty stderr to see that no error is raised and I'm too lazy to fix all the test cases).

Quoted 7 lines

Heh, honesty is good but in this particular case the official reason alone would make perfect sense, too ;-)

As with progress output, shouldn't this automatically be turned off when the standard error stream goes to non tty, as the real purpose of printing is to help the user sitting in front of the terminal and interacting with the command?

I see this at the same level as "Switched to branch 'foo'" which is also protected by opts->quiet. If we start hiding messages based on tty it should be done for other messages in update_refs_for_switch() too, I guess?

Quoted 17 lines · Duy Nguyen

Quoted 8 lines · Junio C Hamano

Quoted 4 lines · Nguyễn Thái Ngọc Duy

Since the purpose of printing this is to help disambiguate. Only do it when "--" is missing (the actual reason though is many tests check empty stderr to see that no error is raised and I'm too lazy to fix all the test cases).

Quoted 7 lines

Heh, honesty is good but in this particular case the official reason alone would make perfect sense, too ;-)

As with progress output, shouldn't this automatically be turned off when the standard error stream goes to non tty, as the real purpose of printing is to help the user sitting in front of the terminal and interacting with the command?

Quoted 4 lines

I see this at the same level as "Switched to branch 'foo'" which is also protected by opts->quiet. If we start hiding messages based on tty it should be done for other messages in update_refs_for_switch() too, I guess?

I have no real opinion either way, but whatever we can do about "checkout" being so confusing since it does so many things is most welcome.

Just an alternative: Maybe we can start this out as advice() output that's either opt-in via config (not on by default) to start with, or have some advice_tty() that only emits it in the same circumstances we emit the progress output?

Quoted 4 lines

Quoted 4 lines

I see this at the same level as "Switched to branch 'foo'" which is also protected by opts->quiet. If we start hiding messages based on tty it should be done for other messages in update_refs_for_switch() too, I guess?

No let's drop this for now. I promise to come back with something better (at least it still sounds better in my mind). If that idea does not work out, we can come back and see if we can improve this.

I promise to come back with something better (at least it still sounds better in my mind). If that idea does not work out, we can come back and see if we can improve this.

Quoted 3 lines · Duy Nguyen

I promise to come back with something better (at least it still sounds better in my mind). If that idea does not work out, we can come back and see if we can improve this.

So this is it. The patch isn't pretty, mostly as a proof of concept. Just look at the three functions at the bottom of checkout.c, which is the main thing.

This patch tries to split "git checkout" command in two new ones:

- git switch-branch is all about switching branches
- git restore-paths (maybe restore-file is better) for checking out paths

The main idea is these two commands will co-exist with the good old 'git checkout', which will NOT be deprecated. Old timers will still use "git checkout". But new people should be introduced to the new two instead. And the new ones are just as capable as "git checkout".

Since the three commands will co-exist (with duplicate functionality), maintenance cost must be kept to minimum. The way I did this is simply split the command line options into three pieces: common, switch-branch and checkout-paths. "git checkout" has all three, the other two have common and another piece.

With this, a new option added to git checkout will be automatically available in either switch-branch or checkout-paths. Bug fixes apply to all relevant commands.

Later on, we could start to add a bit more stuff in, e.g. some form of disambiguation is no longer needed when running as switch-branch, or restore-paths.

So, what do you think?

-- 8< --

builtin.h +2 -0

index 6538932e99..6e321ec8a4 100644
@@ -214,6 +214,7 @@ extern int cmd_remote_fd(int argc, const char **argv, const char *prefix);
 extern int cmd_repack(int argc, const char **argv, const char *prefix);
 extern int cmd_rerere(int argc, const char **argv, const char *prefix);
 extern int cmd_reset(int argc, const char **argv, const char *prefix);
+extern int cmd_restore_paths(int argc, const char **argv, const char *prefix);
 extern int cmd_rev_list(int argc, const char **argv, const char *prefix);
 extern int cmd_rev_parse(int argc, const char **argv, const char *prefix);
 extern int cmd_revert(int argc, const char **argv, const char *prefix);

@@ -227,6 +228,7 @@ extern int cmd_show_index(int argc, const char **argv, const char *prefix);
 extern int cmd_status(int argc, const char **argv, const char *prefix);
 extern int cmd_stripspace(int argc, const char **argv, const char *prefix);
 extern int cmd_submodule__helper(int argc, const char **argv, const char *prefix);
+extern int cmd_switch_branch(int argc, const char **argv, const char *prefix);
 extern int cmd_symbolic_ref(int argc, const char **argv, const char *prefix);
 extern int cmd_tag(int argc, const char **argv, const char *prefix);
 extern int cmd_tar_tree(int argc, const char **argv, const char *prefix);

builtin/checkout.c +158 -76

index acdafc6e4c..868ca3c223 100644
@@ -33,6 +33,16 @@ static const char * const checkout_usage[] = {
 	NULL,
 };
 
+static const char * const switch_branch_usage[] = {
+	N_("git switch-branch [<options>] <branch>"),
+	NULL,
+};
+
+static const char * const restore_paths_usage[] = {
+	N_("git restore-paths [<options>] [<branch>] -- <file>..."),
+	NULL,
+};
+
 struct checkout_opts {
 	int patch_mode;
 	int quiet;

@@ -44,6 +54,7 @@ struct checkout_opts {
 	int ignore_skipworktree;
 	int ignore_other_worktrees;
 	int show_progress;
+	int dwim_new_local_branch;
 	/*
 	 * If new checkout options are added, skip_merge_working_tree
 	 * should be updated accordingly.

@@ -55,6 +66,7 @@ struct checkout_opts {
 	int new_branch_log;
 	enum branch_track track;
 	struct diff_options diff_options;
+	char *conflict_style;
 
 	int branch_exists;
 	const char *prefix;

@@ -1223,78 +1235,105 @@ static int checkout_branch(struct checkout_opts *opts,
 	return switch_branches(opts, new_branch_info);
 }
 
-int cmd_checkout(int argc, const char **argv, const char *prefix)
+static struct option *add_common_options(struct checkout_opts *opts,
+					 struct option *prevopts)
 {
-	struct checkout_opts opts;
-	struct branch_info new_branch_info;
-	char *conflict_style = NULL;
-	int dwim_new_local_branch = 1;
-	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__QUIET(&opts->quiet, N_("suppress progress reporting")),
+		OPT_BOOL(0, "ignore-skip-worktree-bits", &opts->ignore_skipworktree,
+			 N_("do not limit pathspecs to sparse entries only")),
+		{ OPTION_CALLBACK, 0, "recurse-submodules", NULL,
+			    "checkout", "control recursive updating of submodules",
+			    PARSE_OPT_OPTARG, option_parse_recurse_submodules_worktree_updater },
+		OPT_BOOL(0, "progress", &opts->show_progress, N_("force progress reporting")),
+		OPT__FORCE(&opts->force, N_("force checkout (throw away local modifications)"),
+			   PARSE_OPT_NOCOMPLETE),
+		OPT_STRING(0, "conflict", &opts->conflict_style, N_("style"),
+			   N_("conflict style (merge or diff3)")),
+		OPT_END()
+	};
+	struct option *newopts = parse_options_concat(prevopts, options);
+	free(prevopts);
+	return newopts;
+}
+
+static struct option *add_switch_branch_options(struct checkout_opts *opts,
+						struct option *prevopts)
+{
+	struct option options[] = {
+		OPT_STRING('b', NULL, &opts->new_branch, N_("branch"),
 			   N_("create and checkout a new branch")),
-		OPT_STRING('B', NULL, &opts.new_branch_force, N_("branch"),
+		OPT_STRING('B', NULL, &opts->new_branch_force, N_("branch"),
 			   N_("create/reset and checkout a branch")),
-		OPT_BOOL('l', NULL, &opts.new_branch_log, N_("create reflog for new branch")),
-		OPT_BOOL(0, "detach", &opts.force_detach, N_("detach HEAD at named commit")),
-		OPT_SET_INT('t', "track",  &opts.track, N_("set upstream info for new branch"),
+		OPT_BOOL('l', NULL, &opts->new_branch_log, N_("create reflog for new branch")),
+		OPT_BOOL(0, "detach", &opts->force_detach, N_("detach HEAD at named commit")),
+		OPT_SET_INT('t', "track",  &opts->track, N_("set upstream info for new branch"),
 			BRANCH_TRACK_EXPLICIT),
-		OPT_STRING(0, "orphan", &opts.new_orphan_branch, N_("new-branch"), N_("new unparented branch")),
-		OPT_SET_INT_F('2', "ours", &opts.writeout_stage,
+		OPT_STRING(0, "orphan", &opts->new_orphan_branch, N_("new-branch"), N_("new unparented branch")),
+		OPT_BOOL('m', "merge", &opts->merge, N_("perform a 3-way merge with the new branch")),
+		OPT_HIDDEN_BOOL(0, "guess", &opts->dwim_new_local_branch,
+				N_("second guess 'git checkout <no-such-branch>'")),
+		OPT_BOOL(0, "ignore-other-worktrees", &opts->ignore_other_worktrees,
+			 N_("do not check if another worktree is holding the given ref")),
+		OPT_END()
+	};
+	struct option *newopts = parse_options_concat(prevopts, options);
+	free(prevopts);
+	return newopts;
+}
+
+static struct option *add_checkout_path_options(struct checkout_opts *opts,
+						struct option *prevopts)
+{
+	struct option options[] = {
+		OPT_SET_INT_F('2', "ours", &opts->writeout_stage,
 			      N_("checkout our version for unmerged files"),
 			      2, PARSE_OPT_NONEG),
-		OPT_SET_INT_F('3', "theirs", &opts.writeout_stage,
+		OPT_SET_INT_F('3', "theirs", &opts->writeout_stage,
 			      N_("checkout their version for unmerged files"),
 			      3, PARSE_OPT_NONEG),
-		OPT__FORCE(&opts.force, N_("force checkout (throw away local modifications)"),
-			   PARSE_OPT_NOCOMPLETE),
-		OPT_BOOL('m', "merge", &opts.merge, N_("perform a 3-way merge with the new branch")),
-		OPT_BOOL_F(0, "overwrite-ignore", &opts.overwrite_ignore,
-			   N_("update ignored files (default)"),
-			   PARSE_OPT_NOCOMPLETE),
-		OPT_STRING(0, "conflict", &conflict_style, N_("style"),
-			   N_("conflict style (merge or diff3)")),
-		OPT_BOOL('p', "patch", &opts.patch_mode, N_("select hunks interactively")),
-		OPT_BOOL(0, "ignore-skip-worktree-bits", &opts.ignore_skipworktree,
-			 N_("do not limit pathspecs to sparse entries only")),
-		OPT_HIDDEN_BOOL(0, "guess", &dwim_new_local_branch,
-				N_("second guess 'git checkout <no-such-branch>'")),
-		OPT_BOOL(0, "ignore-other-worktrees", &opts.ignore_other_worktrees,
-			 N_("do not check if another worktree is holding the given ref")),
-		{ OPTION_CALLBACK, 0, "recurse-submodules", NULL,
-			    "checkout", "control recursive updating of submodules",
-			    PARSE_OPT_OPTARG, option_parse_recurse_submodules_worktree_updater },
-		OPT_BOOL(0, "progress", &opts.show_progress, N_("force progress reporting")),
-		OPT_END(),
+		OPT_BOOL('p', "patch", &opts->patch_mode, N_("select hunks interactively")),
+		OPT_END()
 	};
+	struct option *newopts = parse_options_concat(prevopts, options);
+	free(prevopts);
+	return newopts;
+}
 
-	memset(&opts, 0, sizeof(opts));
+static int checkout_main(int argc, const char **argv, const char *prefix,
+			 struct checkout_opts *opts, struct option *options,
+			 const char * const usagestr[])
+{
+	struct branch_info new_branch_info;
+	int dwim_remotes_matched = 0;
+
+	memset(opts, 0, sizeof(*opts));
+	opts->dwim_new_local_branch = 1;
 	memset(&new_branch_info, 0, sizeof(new_branch_info));
-	opts.overwrite_ignore = 1;
-	opts.prefix = prefix;
-	opts.show_progress = -1;
+	opts->overwrite_ignore = 1;
+	opts->prefix = prefix;
+	opts->show_progress = -1;
 
-	git_config(git_checkout_config, &opts);
+	git_config(git_checkout_config, opts);
 
-	opts.track = BRANCH_TRACK_UNSPECIFIED;
+	opts->track = BRANCH_TRACK_UNSPECIFIED;
 
-	argc = parse_options(argc, argv, prefix, options, checkout_usage,
+	argc = parse_options(argc, argv, prefix, options, usagestr,
 			     PARSE_OPT_KEEP_DASHDASH);
 
-	if (opts.show_progress < 0) {
-		if (opts.quiet)
-			opts.show_progress = 0;
+	if (opts->show_progress < 0) {
+		if (opts->quiet)
+			opts->show_progress = 0;
 		else
-			opts.show_progress = isatty(2);
+			opts->show_progress = isatty(2);
 	}
 
-	if (conflict_style) {
-		opts.merge = 1; /* implied */
-		git_xmerge_config("merge.conflictstyle", conflict_style, NULL);
+	if (opts->conflict_style) {
+		opts->merge = 1; /* implied */
+		git_xmerge_config("merge.conflictstyle", opts->conflict_style, NULL);
 	}
 
-	if ((!!opts.new_branch + !!opts.new_branch_force + !!opts.new_orphan_branch) > 1)
+	if ((!!opts->new_branch + !!opts->new_branch_force + !!opts->new_orphan_branch) > 1)
 		die(_("-b, -B and --orphan are mutually exclusive"));
 
 	/*

@@ -1302,14 +1341,14 @@ int cmd_checkout(int argc, const char **argv, const char *prefix)
 	 * and new_branch_force and new_orphan_branch will tell us which one of
 	 * -b/-B/--orphan is being used.
 	 */
-	if (opts.new_branch_force)
-		opts.new_branch = opts.new_branch_force;
+	if (opts->new_branch_force)
+		opts->new_branch = opts->new_branch_force;
 
-	if (opts.new_orphan_branch)
-		opts.new_branch = opts.new_orphan_branch;
+	if (opts->new_orphan_branch)
+		opts->new_branch = opts->new_orphan_branch;
 
 	/* --track without -b/-B/--orphan should DWIM */
-	if (opts.track != BRANCH_TRACK_UNSPECIFIED && !opts.new_branch) {
+	if (opts->track != BRANCH_TRACK_UNSPECIFIED && !opts->new_branch) {
 		const char *argv0 = argv[0];
 		if (!argc || !strcmp(argv0, "--"))
 			die(_("--track needs a branch name"));

@@ -1318,7 +1357,7 @@ int cmd_checkout(int argc, const char **argv, const char *prefix)
 		argv0 = strchr(argv0, '/');
 		if (!argv0 || !argv0[1])
 			die(_("missing branch name; try -b"));
-		opts.new_branch = argv0 + 1;
+		opts->new_branch = argv0 + 1;
 	}
 
 	/*

@@ -1337,56 +1376,56 @@ int cmd_checkout(int argc, const char **argv, const char *prefix)
 	if (argc) {
 		struct object_id rev;
 		int dwim_ok =
-			!opts.patch_mode &&
-			dwim_new_local_branch &&
-			opts.track == BRANCH_TRACK_UNSPECIFIED &&
-			!opts.new_branch;
+			!opts->patch_mode &&
+			opts->dwim_new_local_branch &&
+			opts->track == BRANCH_TRACK_UNSPECIFIED &&
+			!opts->new_branch;
 		int n = parse_branchname_arg(argc, argv, dwim_ok,
-					     &new_branch_info, &opts, &rev,
+					     &new_branch_info, opts, &rev,
 					     &dwim_remotes_matched);
 		argv += n;
 		argc -= n;
 	}
 
 	if (argc) {
-		parse_pathspec(&opts.pathspec, 0,
-			       opts.patch_mode ? PATHSPEC_PREFIX_ORIGIN : 0,
+		parse_pathspec(&opts->pathspec, 0,
+			       opts->patch_mode ? PATHSPEC_PREFIX_ORIGIN : 0,
 			       prefix, argv);
 
-		if (!opts.pathspec.nr)
+		if (!opts->pathspec.nr)
 			die(_("invalid path specification"));
 
 		/*
 		 * Try to give more helpful suggestion.
 		 * new_branch && argc > 1 will be caught later.
 		 */
-		if (opts.new_branch && argc == 1)
+		if (opts->new_branch && argc == 1)
 			die(_("'%s' is not a commit and a branch '%s' cannot be created from it"),
-				argv[0], opts.new_branch);
+				argv[0], opts->new_branch);
 
-		if (opts.force_detach)
+		if (opts->force_detach)
 			die(_("git checkout: --detach does not take a path argument '%s'"),
 			    argv[0]);
 
-		if (1 < !!opts.writeout_stage + !!opts.force + !!opts.merge)
+		if (1 < !!opts->writeout_stage + !!opts->force + !!opts->merge)
 			die(_("git checkout: --ours/--theirs, --force and --merge are incompatible when\n"
 			      "checking out of the index."));
 	}
 
-	if (opts.new_branch) {
+	if (opts->new_branch) {
 		struct strbuf buf = STRBUF_INIT;
 
-		if (opts.new_branch_force)
-			opts.branch_exists = validate_branchname(opts.new_branch, &buf);
+		if (opts->new_branch_force)
+			opts->branch_exists = validate_branchname(opts->new_branch, &buf);
 		else
-			opts.branch_exists =
-				validate_new_branchname(opts.new_branch, &buf, 0);
+			opts->branch_exists =
+				validate_new_branchname(opts->new_branch, &buf, 0);
 		strbuf_release(&buf);
 	}
 
 	UNLEAK(opts);
-	if (opts.patch_mode || opts.pathspec.nr) {
-		int ret = checkout_paths(&opts, new_branch_info.name);
+	if (opts->patch_mode || opts->pathspec.nr) {
+		int ret = checkout_paths(opts, new_branch_info.name);
 		if (ret && dwim_remotes_matched > 1 &&
 		    advice_checkout_ambiguous_remote_branch_name)
 			advise(_("'%s' matched more than one remote tracking branch.\n"

@@ -1405,6 +1444,49 @@ int cmd_checkout(int argc, const char **argv, const char *prefix)
 			       dwim_remotes_matched);
 		return ret;
 	} else {
-		return checkout_branch(&opts, &new_branch_info);
+		return checkout_branch(opts, &new_branch_info);
 	}
 }
+
+int cmd_checkout(int argc, const char **argv, const char *prefix)
+{
+	struct checkout_opts opts;
+	struct option *options = NULL;
+	int ret;
+
+	options = add_common_options(&opts, options);
+	options = add_switch_branch_options(&opts, options);
+	options = add_checkout_path_options(&opts, options);
+	ret = checkout_main(argc, argv, prefix, &opts,
+			    options, checkout_usage);
+	FREE_AND_NULL(options);
+	return ret;
+}
+
+int cmd_switch_branch(int argc, const char **argv, const char *prefix)
+{
+	struct checkout_opts opts;
+	struct option *options = NULL;
+	int ret;
+
+	options = add_common_options(&opts, options);
+	options = add_switch_branch_options(&opts, options);
+	ret = checkout_main(argc, argv, prefix, &opts,
+			    options, switch_branch_usage);
+	FREE_AND_NULL(options);
+	return ret;
+}
+
+int cmd_restore_paths(int argc, const char **argv, const char *prefix)
+{
+	struct checkout_opts opts;
+	struct option *options = NULL;
+	int ret;
+
+	options = add_common_options(&opts, options);
+	options = add_checkout_path_options(&opts, options);
+	ret = checkout_main(argc, argv, prefix, &opts,
+			    options, restore_paths_usage);
+	FREE_AND_NULL(options);
+	return ret;
+}

git.c +2 -0

index 2f604a41ea..e8a76a99da 100644
@@ -542,6 +542,7 @@ static struct cmd_struct commands[] = {
 	{ "replace", cmd_replace, RUN_SETUP },
 	{ "rerere", cmd_rerere, RUN_SETUP },
 	{ "reset", cmd_reset, RUN_SETUP },
+	{ "restore-paths", cmd_restore_paths, RUN_SETUP | NEED_WORK_TREE },
 	{ "rev-list", cmd_rev_list, RUN_SETUP | NO_PARSEOPT },
 	{ "rev-parse", cmd_rev_parse, NO_PARSEOPT },
 	{ "revert", cmd_revert, RUN_SETUP | NEED_WORK_TREE },

@@ -557,6 +558,7 @@ static struct cmd_struct commands[] = {
 	{ "status", cmd_status, RUN_SETUP | NEED_WORK_TREE },
 	{ "stripspace", cmd_stripspace },
 	{ "submodule--helper", cmd_submodule__helper, RUN_SETUP | SUPPORT_SUPER_PREFIX | NO_PARSEOPT },
+	{ "switch-branch", cmd_switch_branch, RUN_SETUP | NEED_WORK_TREE },
 	{ "symbolic-ref", cmd_symbolic_ref, RUN_SETUP },
 	{ "tag", cmd_tag, RUN_SETUP | DELAY_PAGER_CONFIG },
 	{ "unpack-file", cmd_unpack_file, RUN_SETUP | NO_PARSEOPT },

parse-options-cb.c +1 -2

index 8c9edce52f..c609d52926 100644
@@ -126,7 +126,7 @@ struct option *parse_options_concat(struct option *a, struct option *b)
 	struct option *ret;
 	size_t i, a_len = 0, b_len = 0;
 
-	for (i = 0; a[i].type != OPTION_END; i++)
+	for (i = 0; a && a[i].type != OPTION_END; i++)
 		a_len++;
 	for (i = 0; b[i].type != OPTION_END; i++)
 		b_len++;
-- 8< --

I like the idea of splitting those commands up, in fact it is something I've been considering working on myself. I do think we should consider if we want to change the behaviour of those new commands in any way compared to 'git checkout', since we're starting with a clean slate.

One thing in particular that I have in mind is something I'm currently working on, namely adding a --index flag to 'git checkout', which would make 'git checkout' work in non-overlay mode (for more discussion on that see also [*1*].

Quoted 5 lines · Thomas Gummerer

I like the idea of splitting those commands up, in fact it is something I've been considering working on myself. I do think we should consider if we want to change the behaviour of those new commands in any way compared to 'git checkout', since we're starting with a clean slate.

Quoted 4 lines

One thing in particular that I have in mind is something I'm currently working on, namely adding a --index flag to 'git checkout', which would make 'git checkout' work in non-overlay mode (for more discussion on that see also [*1*].

Ah, thanks for reminding me of that. That explains why I felt uneasy to see "restore" in the proposed command name.

Quoted 3 lines · Duy Nguyen

I promise to come back with something better (at least it still sounds better in my mind). If that idea does not work out, we can come back and see if we can improve this.

So this is it. The patch isn't pretty, mostly as a proof of concept. Just look at the three functions at the bottom of checkout.c, which is the main thing.

This patch tries to split "git checkout" command in two new ones:

- git switch-branch is all about switching branches

- git restore-paths (maybe restore-file is better) for checking out paths

The main idea is these two commands will co-exist with the good old 'git checkout', which will NOT be deprecated. Old timers will still use "git checkout". But new people should be introduced to the new two instead. And the new ones are just as capable as "git checkout".

Since the three commands will co-exist (with duplicate functionality), maintenance cost must be kept to minimum. The way I did this is simply split the command line options into three pieces: common, switch-branch and checkout-paths. "git checkout" has all three, the other two have common and another piece.

With this, a new option added to git checkout will be automatically available in either switch-branch or checkout-paths. Bug fixes apply to all relevant commands.

Later on, we could start to add a bit more stuff in, e.g. some form of disambiguation is no longer needed when running as switch-branch, or restore-paths.

So, what do you think?

Quoted 1 line

So, what do you think?

That "git checkout" does too many things is something that keeps coming up in online discussions about Git's UI. Two things:

a) It would really help to have some comparison of cases where these split commands are much clearer or less ambiguous than git-checkout. I can think of some (e.g. branch with the same name as a file) but having some overall picture of what the new UI looks like with solved / not solved cases would be nice. Also a comparison with other SCMs people find less confusing (svn, hg, bzr, ...)

b) I think we really need to have some end-game where we'd actually switch away from "checkout" (which we could still auto-route to new commands in perpetuity, but print a warning or error). Otherwise we'll just end up with https://xkcd.com/927/ and more UI confusion for all.

Quoted 9 lines · Duy Nguyen

Quoted 3 lines · Duy Nguyen

I promise to come back with something better (at least it still sounds better in my mind). If that idea does not work out, we can come back and see if we can improve this.

So this is it. The patch isn't pretty, mostly as a proof of concept. Just look at the three functions at the bottom of checkout.c, which is the main thing.

Quoted 3 lines

This patch tries to split "git checkout" command in two new ones:

- git switch-branch is all about switching branches

Isn't this going to also take the other ref arguments 'git checkout' takes now? I.e. tags, detached HEADs etc? I'm reminded of the discussion about what "range-diff" should be called :)

Quoted 3 lines

- git restore-paths (maybe restore-file is better) for checking out paths

Quoted 5 lines

Later on, we could start to add a bit more stuff in, e.g. some form of disambiguation is no longer needed when running as switch-branch, or restore-paths.

So, what do you think?

That "git checkout" does too many things is something that keeps coming up in online discussions about Git's UI. Two things:

a) It would really help to have some comparison of cases where these split commands are much clearer or less ambiguous than git-checkout. I can think of some (e.g. branch with the same name as a file) but having some overall picture of what the new UI looks like with solved / not solved cases would be nice. Also a comparison with other SCMs people find less confusing (svn, hg, bzr, ...)

b) I think we really need to have some end-game where we'd actually switch away from "checkout" (which we could still auto-route to new commands in perpetuity, but print a warning or error). Otherwise we'll just end up with https://xkcd.com/927/ and more UI confusion for all.

Maybe we need to step back and consider what the command does. And from that I would name it "rewire-HEAD-and-update-index&worktree" and then simplify from there. For the beginner user, the concept of HEAD might be overwhelming, such that we don't want to have that in there.

"content-to-path", maybe(?) ...

git tree-to-worktree # git checkout <commit> -- <path> git index-to-worktree # git checkout -- <path>

There is currently no caller that calls this function with "a" being NULL. But it will be introduced shortly. It is used to construct the option array from scratch, e.g.

   struct parse_options opts = NULL;
   opts = parse_options_concat(opts, opts_1);
   opts = parse_options_concat(opts, opts_2);

Signed-off-by Nguyễn Thái Ngọc Duy <[email protected]>

There is currently no caller that calls this function with "a" being NULL. But it will be introduced shortly. It is used to construct the option array from scratch, e.g.

   struct parse_options opts = NULL;

   opts = parse_options_concat(opts, opts_1);
   opts = parse_options_concat(opts, opts_2);

Signed-off-by Nguyễn Thái Ngọc Duy <[email protected]>

---
 parse-options-cb.c | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

parse-options-cb.c +1 -1

index 8c9edce52f..c609d52926 100644
@@ -126,7 +126,7 @@ struct option *parse_options_concat(struct option *a, struct option *b)
 	struct option *ret;
 	size_t i, a_len = 0, b_len = 0;
 
-	for (i = 0; a[i].type != OPTION_END; i++)
+	for (i = 0; a && a[i].type != OPTION_END; i++)
 		a_len++;
 	for (i = 0; b[i].type != OPTION_END; i++)
 		b_len++;

The good old "git checkout" command is still here and will be until all (or most of users) are sick of it.

builtin/checkout.c +66 -13

 	/*
 	 * If new checkout options are added, skip_merge_working_tree

@@ -1056,7 +1068,7 @@ static int parse_branchname_arg(int argc, const char **argv,
 	arg = argv[0];
 	dash_dash_pos = -1;
 	for (i = 0; i < argc; i++) {
-		if (!strcmp(argv[i], "--")) {
+		if (opts->accept_pathspec && !strcmp(argv[i], "--")) {
 			dash_dash_pos = i;
 			break;
 		}

@@ -1067,6 +1079,8 @@ static int parse_branchname_arg(int argc, const char **argv,
 		has_dash_dash = 1; /* case (3) or (1) */
 	else if (dash_dash_pos >= 2)
 		die(_("only one reference expected, %d given."), dash_dash_pos);
+	else if (!opts->accept_pathspec)
+		has_dash_dash = 1;
 
 	if (!strcmp(arg, "-"))
 		arg = "@{-1}";

@@ -1291,30 +1305,23 @@ static struct option *add_checkout_path_options(struct checkout_opts *opts,
 	return newopts;
 }
 
-int cmd_checkout(int argc, const char **argv, const char *prefix)
+static int checkout_main(int argc, const char **argv, const char *prefix,
+			 struct checkout_opts *opts, struct option *options,
+			 const char * const usagestr[])
 {
-	struct checkout_opts real_opts;
-	struct checkout_opts *opts = &real_opts;
 	struct branch_info new_branch_info;
 	int dwim_remotes_matched = 0;
-	struct option *options = NULL;
 
-	memset(opts, 0, sizeof(*opts));
 	memset(&new_branch_info, 0, sizeof(new_branch_info));
 	opts->overwrite_ignore = 1;
 	opts->prefix = prefix;
 	opts->show_progress = -1;
-	opts->dwim_new_local_branch = 1;
 
 	git_config(git_checkout_config, opts);
 
 	opts->track = BRANCH_TRACK_UNSPECIFIED;
 
-	options = add_common_options(opts, options);
-	options = add_switch_branch_options(opts, options);
-	options = add_checkout_path_options(opts, options);
-
-	argc = parse_options(argc, argv, prefix, options, checkout_usage,
+	argc = parse_options(argc, argv, prefix, options, usagestr,
 			     PARSE_OPT_KEEP_DASHDASH);
 
 	if (opts->show_progress < 0) {

@@ -1381,7 +1388,8 @@ int cmd_checkout(int argc, const char **argv, const char *prefix)
 					     &dwim_remotes_matched);
 		argv += n;
 		argc -= n;
-	}
+	} else if (!opts->empty_arg_ok)
+		usage_with_options(usagestr, options);
 
 	if (argc) {
 		parse_pathspec(&opts->pathspec, 0,

@@ -1443,3 +1451,60 @@ int cmd_checkout(int argc, const char **argv, const char *prefix)
 		return checkout_branch(opts, &new_branch_info);
 	}
 }
+
+int cmd_checkout(int argc, const char **argv, const char *prefix)
+{
+	struct checkout_opts opts;
+	struct option *options = NULL;
+	int ret;
+
+	memset(&opts, 0, sizeof(opts));
+	opts.dwim_new_local_branch = 1;
+	opts.accept_pathspec = 1;
+	opts.empty_arg_ok = 1;
+
+	options = add_common_options(&opts, options);
+	options = add_switch_branch_options(&opts, options);
+	options = add_checkout_path_options(&opts, options);
+
+	ret = checkout_main(argc, argv, prefix, &opts,
+			    options, checkout_usage);
+	FREE_AND_NULL(options);
+	return ret;
+}
+
+int cmd_switch_branch(int argc, const char **argv, const char *prefix)
+{
+	struct checkout_opts opts;
+	struct option *options = NULL;
+	int ret;
+
+	memset(&opts, 0, sizeof(opts));
+	opts.dwim_new_local_branch = 1;
+
+	options = add_common_options(&opts, options);
+	options = add_switch_branch_options(&opts, options);
+
+	ret = checkout_main(argc, argv, prefix, &opts,
+			    options, switch_branch_usage);
+	FREE_AND_NULL(options);
+	return ret;
+}
+
+int cmd_checkout_files(int argc, const char **argv, const char *prefix)
+{
+	struct checkout_opts opts;
+	struct option *options = NULL;
+	int ret;
+
+	memset(&opts, 0, sizeof(opts));
+	opts.accept_pathspec = 1;
+
+	options = add_common_options(&opts, options);
+	options = add_checkout_path_options(&opts, options);
+
+	ret = checkout_main(argc, argv, prefix, &opts,
+			    options, checkout_files_usage);
+	FREE_AND_NULL(options);
+	return ret;
+}

git.c +2 -0

index 2f604a41ea..3b86ba765c 100644
@@ -457,6 +457,7 @@ static struct cmd_struct commands[] = {
 	{ "check-mailmap", cmd_check_mailmap, RUN_SETUP },
 	{ "check-ref-format", cmd_check_ref_format, NO_PARSEOPT  },
 	{ "checkout", cmd_checkout, RUN_SETUP | NEED_WORK_TREE },
+	{ "checkout-files", cmd_checkout_files, RUN_SETUP | NEED_WORK_TREE },
 	{ "checkout-index", cmd_checkout_index,
 		RUN_SETUP | NEED_WORK_TREE},
 	{ "cherry", cmd_cherry, RUN_SETUP },

@@ -557,6 +558,7 @@ static struct cmd_struct commands[] = {
 	{ "status", cmd_status, RUN_SETUP | NEED_WORK_TREE },
 	{ "stripspace", cmd_stripspace },
 	{ "submodule--helper", cmd_submodule__helper, RUN_SETUP | SUPPORT_SUPER_PREFIX | NO_PARSEOPT },
+	{ "switch-branch", cmd_switch_branch, RUN_SETUP | NEED_WORK_TREE },
 	{ "symbolic-ref", cmd_symbolic_ref, RUN_SETUP },
 	{ "tag", cmd_tag, RUN_SETUP | DELAY_PAGER_CONFIG },
 	{ "unpack-file", cmd_unpack_file, RUN_SETUP | NO_PARSEOPT },

The assumption made is here

- "git checkout" is a horrible monster that should only be touched with a two-meter pole

- there are other commands that can achieve the same thing

Signed-off-by Nguyễn Thái Ngọc Duy <[email protected]>

---
 Documentation/git-branch.txt           |  8 ++--
 Documentation/git-check-ref-format.txt |  2 +-
 Documentation/git-format-patch.txt     |  2 +-
 Documentation/git-merge-base.txt       |  2 +-
 Documentation/git-rebase.txt           |  2 +-
 Documentation/git-remote.txt           |  2 +-
 Documentation/git-rerere.txt           | 10 ++---
 Documentation/git-reset.txt            | 18 ++++-----
 Documentation/git-revert.txt           |  2 +-
 Documentation/git-stash.txt            |  6 +--
 Documentation/gitattributes.txt        |  2 +-
 Documentation/gitcli.txt               |  4 +-
 Documentation/gitcore-tutorial.txt     | 18 ++++-----
 Documentation/giteveryday.txt          | 24 ++++++------
 Documentation/githooks.txt             |  5 ++-
 Documentation/gittutorial-2.txt        |  2 +-
 Documentation/gittutorial.txt          |  4 +-
 Documentation/revisions.txt            |  2 +-
 Documentation/user-manual.txt          | 54 +++++++++++++-------------
 advice.c                               |  2 +-
 sha1-name.c                            |  2 +-
 wt-status.c                            |  2 +-
 22 files changed, 88 insertions(+), 87 deletions(-)

Documentation/git-branch.txt +4 -4

index bf5316ffa9..1564df47d2 100644
@@ -48,7 +48,7 @@ The command's second form creates a new branch head named <branchname>
 which points to the current `HEAD`, or <start-point> if given.
 
 Note that this will create the new branch, but it will not switch the
-working tree to it; use "git checkout <newbranch>" to switch to the
+working tree to it; use "git switch-branch <newbranch>" to switch to the
 new branch.
 
 When a local branch is started off a remote-tracking branch, Git sets up the

@@ -194,7 +194,7 @@ This option is only applicable in non-verbose mode.
 +
 This behavior is the default when the start point is a remote-tracking branch.
 Set the branch.autoSetupMerge configuration variable to `false` if you
-want `git checkout` and `git branch` to always behave as if `--no-track`
+want `git switch-branch` and `git branch` to always behave as if `--no-track`
 were given. Set it to `always` if you want this behavior when the
 start-point is either a local or remote-tracking branch.
 

@@ -293,7 +293,7 @@ Start development from a known tag::
 $ git clone git://git.kernel.org/pub/scm/.../linux-2.6 my2.6
 $ cd my2.6
 $ git branch my2.6.14 v2.6.14   <1>
-$ git checkout my2.6.14
+$ git switch-branch my2.6.14
 ------------
 +
 <1> This step and the next one could be combined into a single step with

@@ -319,7 +319,7 @@ NOTES
 -----
 
 If you are creating a branch that you want to checkout immediately, it is
-easier to use the git checkout command with its `-b` option to create
+easier to use the "git switch-branch" command with its `-b` option to create
 a branch and check it out with a single command.
 
 The options `--contains`, `--no-contains`, `--merged` and `--no-merged`

Documentation/git-check-ref-format.txt +1 -1

index d9de992585..38c2169d7a 100644
@@ -88,7 +88,7 @@ but it is explicitly forbidden at the beginning of a branch name).
 When run with `--branch` option in a repository, the input is first
 expanded for the ``previous checkout syntax''
 `@{-n}`.  For example, `@{-1}` is a way to refer the last thing that
-was checked out using "git checkout" operation. This option should be
+was checked out using "git switch-branch" operation. This option should be
 used by porcelains to accept this syntax anywhere a branch name is
 expected, so they can act as if you typed the branch name. As an
 exception note that, the ``previous checkout operation'' might result

Documentation/git-format-patch.txt +1 -1

index aba4c5febe..0ceaa1173c 100644
@@ -416,7 +416,7 @@ One way to test if your MUA is set up correctly is:
 * Apply it:
 
     $ git fetch <project> master:test-apply
-    $ git checkout test-apply
+    $ git switch-branch test-apply
     $ git reset --hard
     $ git am a.patch
 

Documentation/git-merge-base.txt +1 -1

index 9f07f4f6ed..1b25e5d530 100644
@@ -149,7 +149,7 @@ instead.
 Discussion on fork-point mode
 -----------------------------
 
-After working on the `topic` branch created with `git checkout -b
+After working on the `topic` branch created with `git switch-branch -b
 topic origin/master`, the history of remote-tracking branch
 `origin/master` may have been rewound and rebuilt, leading to a
 history of this shape:

Documentation/git-rebase.txt +1 -1

index 80793bad8d..fe10880633 100644
@@ -17,7 +17,7 @@ SYNOPSIS
 DESCRIPTION
 -----------
 If <branch> is specified, 'git rebase' will perform an automatic
-`git checkout <branch>` before doing anything else.  Otherwise
+`git switch-branch <branch>` before doing anything else.  Otherwise
 it remains on the current branch.
 
 If <upstream> is not specified, the upstream configured in

Documentation/git-remote.txt +1 -1

index 0cad37fb81..044bbdb27c 100644
@@ -230,7 +230,7 @@ $ git branch -r
   staging/master
   staging/staging-linus
   staging/staging-next
-$ git checkout -b staging staging/master
+$ git switch-branch -b staging staging/master
...
 ------------

Documentation/git-rerere.txt +5 -5

index df310d2a58..fe9d21b395 100644
@@ -91,7 +91,7 @@ For such a test, you need to merge master and topic somehow.
 One way to do it is to pull master into the topic branch:
 
 ------------
-	$ git checkout topic
+	$ git switch-branch topic
 	$ git merge master
 
               o---*---o---+ topic

@@ -113,10 +113,10 @@ the upstream might have been advanced since the test merge `+`,
 in which case the final commit graph would look like this:
 
 ------------
-	$ git checkout topic
+	$ git switch-branch topic
 	$ git merge master
 	$ ... work on both topic and master branches
-	$ git checkout master
+	$ git switch-branch master
 	$ git merge topic
 
               o---*---o---+---o---o topic

@@ -136,11 +136,11 @@ merges, you could blow away the test merge, and keep building on
 top of the tip before the test merge:
 
 ------------
-	$ git checkout topic
+	$ git switch-branch topic
 	$ git merge master
 	$ git reset --hard HEAD^ ;# rewind the test merge
 	$ ... work on both topic and master branches
-	$ git checkout master
+	$ git switch-branch master
 	$ git merge topic
 
               o---*---o-------o---o topic

Documentation/git-reset.txt +9 -9

index 2dac95c71a..ca46b4c967 100644
@@ -149,9 +149,9 @@ See also the --amend option to linkgit:git-commit[1].
 Undo a commit, making it a topic branch::
 +
 ------------
-$ git branch topic/wip     <1>
-$ git reset --hard HEAD~3  <2>
-$ git checkout topic/wip   <3>
+$ git branch topic/wip          <1>
+$ git reset --hard HEAD~3       <2>
+$ git switch-branch topic/wip   <3>
 ------------
 +
 <1> You have made some commits, but realize they were premature

@@ -232,13 +232,13 @@ working tree are not in any shape to be committed yet, but you
 need to get to the other branch for a quick bugfix.
 +
 ------------
-$ git checkout feature ;# you were working in "feature" branch and
+$ git switch-branch feature ;# you were working in "feature" branch and
 $ work work work       ;# got interrupted
 $ git commit -a -m "snapshot WIP"                 <1>
-$ git checkout master
+$ git switch-branch master
 $ fix fix fix
 $ git commit ;# commit with real log
-$ git checkout feature
+$ git switch-branch feature
 $ git reset --soft HEAD^ ;# go back to WIP state  <2>
 $ git reset                                       <3>
 ------------

@@ -279,18 +279,18 @@ reset it while keeping the changes in your working tree.
 +
 ------------
 $ git tag start
-$ git checkout -b branch1
+$ git switch-branch -b branch1
 $ edit
 $ git commit ...                            <1>
 $ edit
-$ git checkout -b branch2                   <2>
+$ git switch-branch -b branch2              <2>
 $ git reset --keep start                    <3>
 ------------
 +
 <1> This commits your first edits in branch1.
 <2> In the ideal world, you could have realized that the earlier
     commit did not belong to the new topic when you created and switched
-    to branch2 (i.e. "git checkout -b branch2 start"), but nobody is
+    to branch2 (i.e. "git switch-branch -b branch2 start"), but nobody is
     perfect.
 <3> But you can use "reset --keep" to remove the unwanted commit after
     you switched to "branch2".

Documentation/git-revert.txt +1 -1

index 837707a8fd..e49dbbec83 100644
@@ -26,7 +26,7 @@ effect of some earlier commits (often only a faulty one).  If you want to
 throw away all uncommitted changes in your working directory, you
 should see linkgit:git-reset[1], particularly the `--hard` option.  If
 you want to extract specific files as they were in another commit, you
-should see linkgit:git-checkout[1], specifically the `git checkout
+should see linkgit:git-checkout[1], specifically the `git checkout-files
 <commit> -- <filename>` syntax.  Take care with these alternatives as
 both will discard uncommitted changes in your working directory.
 

Documentation/git-stash.txt +3 -3

index 7ef8c47911..ea226979b1 100644
@@ -235,12 +235,12 @@ return to your original branch to make the emergency fix, like this:
 +
 ----------------------------------------------------------------
 # ... hack hack hack ...
-$ git checkout -b my_wip
+$ git switch-branch -b my_wip
 $ git commit -a -m "WIP"
-$ git checkout master
+$ git switch-branch master
 $ edit emergency fix
 $ git commit -a -m "Fix in a hurry"
-$ git checkout my_wip
+$ git switch-branch my_wip
 $ git reset --soft HEAD^
 # ... continue hacking ...
 ----------------------------------------------------------------

Documentation/gitattributes.txt +1 -1

index b8392fc330..df62bd8019 100644
@@ -112,7 +112,7 @@ Checking-out and checking-in
 
 These attributes affect how the contents stored in the
 repository are copied to the working tree files when commands
-such as 'git checkout' and 'git merge' run.  They also affect how
+such as 'git switch-branch' and 'git merge' run.  They also affect how
 Git stores the contents you prepare in the working tree in the
 repository upon 'git add' and 'git commit'.
 

Documentation/gitcli.txt +2 -2

index 592e06d839..0ad4869f2c 100644
@@ -47,8 +47,8 @@ disambiguating `--` at appropriate places.
    things:
 +
 --------------------------------
-$ git checkout -- *.c
-$ git checkout -- \*.c
+$ git checkout-files -- *.c
+$ git checkout-files -- \*.c
 --------------------------------
 +
 The former lets your shell expand the fileglob, and you are asking

Documentation/gitcore-tutorial.txt +9 -9

index e29a9effcc..49a8b5aa52 100644
@@ -741,7 +741,7 @@ used earlier, and create a branch in it. You do that by simply just
 saying that you want to check out a new branch:
 
 ------------
-$ git checkout -b mybranch
+$ git branch mybranch
 ------------
 
 will create a new branch based at the current `HEAD` position, and switch

@@ -755,7 +755,7 @@ just telling 'git checkout' what the base of the checkout would be.
 In other words, if you have an earlier tag or branch, you'd just do
 
 ------------
-$ git checkout -b mybranch earlier-commit
+$ git switch-branch -b mybranch earlier-commit
 ------------
 
 and it would create the new branch `mybranch` at the earlier commit,

@@ -765,7 +765,7 @@ and check out the state at that time.
 You can always just jump back to your original `master` branch by doing
 
 ------------
-$ git checkout master
+$ git switch-branch master
 ------------
 
 (or any other branch-name, for that matter) and if you forget which

@@ -794,7 +794,7 @@ $ git branch <branchname> [startingpoint]
 
 which will simply _create_ the branch, but will not do anything further.
 You can then later -- once you decide that you want to actually develop
-on that branch -- switch to that branch with a regular 'git checkout'
+on that branch -- switch to that branch with a regular 'git switch-branch
 with the branchname as the argument.
 
 

@@ -808,7 +808,7 @@ being the same as the original `master` branch, let's make sure we're in
 that branch, and do some work there.
 
 ------------------------------------------------
-$ git checkout mybranch
+$ git switch-branch mybranch
 $ echo "Work, work, work" >>hello
 $ git commit -m "Some work." -i hello
 ------------------------------------------------

@@ -825,7 +825,7 @@ does some work in the original branch, and simulate that by going back
 to the master branch, and editing the same file differently there:
 
 ------------
-$ git checkout master
+$ git switch-branch master
 ------------
 
 Here, take a moment to look at the contents of `hello`, and notice how they

@@ -958,7 +958,7 @@ to the `master` branch. Let's go back to `mybranch`, and run
 'git merge' to get the "upstream changes" back to your branch.
 
 ------------
-$ git checkout mybranch
+$ git switch-branch mybranch
 $ git merge -m "Merge upstream changes." master
 ------------
 

@@ -1133,9 +1133,9 @@ Remember, before running 'git merge', our `master` head was at
 work." commit.
 
 ------------
-$ git checkout mybranch
+$ git switch-branch mybranch
 $ git reset --hard master^2
-$ git checkout master
+$ git switch-branch master
 $ git reset --hard master^
 ------------
 

Documentation/giteveryday.txt +12 -12

index 9f2528fc8c..861b2bb616 100644
@@ -80,9 +80,9 @@ $ git tag v2.43 <2>
 Create a topic branch and develop.::
 +
 ------------
-$ git checkout -b alsa-audio <1>
+$ git branch alsa-audio <1>
 $ edit/compile/test
-$ git checkout -- curses/ux_audio_oss.c <2>
+$ git checkout-files -- curses/ux_audio_oss.c <2>
 $ git add curses/ux_audio_alsa.c <3>
 $ edit/compile/test
 $ git diff HEAD <4>

@@ -90,7 +90,7 @@ $ git commit -a -s <5>
 $ edit/compile/test
 $ git diff HEAD^ <6>
 $ git commit -a --amend <7>
-$ git checkout master <8>
+$ git switch-branch master <8>
 $ git merge alsa-audio <9>
 $ git log --since='3 days ago' <10>
 $ git log v2.43.. curses/ <11>

@@ -148,11 +148,11 @@ Clone the upstream and work on it.  Feed changes to upstream.::
 ------------
 $ git clone git://git.kernel.org/pub/scm/.../torvalds/linux-2.6 my2.6
 $ cd my2.6
-$ git checkout -b mine master <1>
+$ git switch-branch -b mine master <1>
 $ edit/compile/test; git commit -a -s <2>
 $ git format-patch master <3>
 $ git send-email --to="person <[email protected]>" 00*.patch <4>
-$ git checkout master <5>
+$ git switch-branch master <5>
 $ git pull <6>
 $ git log -p ORIG_HEAD.. arch/i386 include/asm-i386 <7>
 $ git ls-remote --heads http://git.kernel.org/.../jgarzik/libata-dev.git <8>

@@ -194,7 +194,7 @@ satellite$ edit/compile/test/commit
 satellite$ git push origin <4>
 
 mothership$ cd frotz
-mothership$ git checkout master
+mothership$ git switch-branch master
 mothership$ git merge satellite/master <5>
 ------------
 +

@@ -216,7 +216,7 @@ machine into the master branch.
 Branch off of a specific tag.::
 +
 ------------
-$ git checkout -b private2.6.14 v2.6.14 <1>
+$ git switch-branch -b private2.6.14 v2.6.14 <1>
 $ edit/compile/test; git commit -a
 $ git checkout master
 $ git cherry-pick v2.6.14..private2.6.14 <2>

@@ -274,14 +274,14 @@ $ mailx <3>
 & s 2 3 4 5 ./+to-apply
 & s 7 8 ./+hold-linus
 & q
-$ git checkout -b topic/one master
+$ git switch-branch -b topic/one master
 $ git am -3 -i -s ./+to-apply <4>
 $ compile/test
-$ git checkout -b hold/linus && git am -3 -i -s ./+hold-linus <5>
-$ git checkout topic/one && git rebase master <6>
-$ git checkout pu && git reset --hard next <7>
+$ git switch-branch -b hold/linus && git am -3 -i -s ./+hold-linus <5>
+$ git switch-branch topic/one && git rebase master <6>
+$ git switch-branch pu && git reset --hard next <7>
 $ git merge topic/one topic/two && git merge hold/linus <8>
-$ git checkout maint
+$ git switch-branch maint
 $ git cherry-pick master~4 <9>
 $ compile/test
 $ git tag -s -m "GIT 0.99.9x" v0.99.9x <10>

Documentation/githooks.txt +3 -2

index 959044347e..3939ec774a 100644
@@ -166,7 +166,7 @@ worktree.  The hook is given three parameters: the ref of the previous HEAD,
 the ref of the new HEAD (which may or may not have changed), and a flag
 indicating whether the checkout was a branch checkout (changing branches,
 flag=1) or a file checkout (retrieving a file from the index, flag=0).
-This hook cannot affect the outcome of `git checkout`.
+This hook cannot affect the outcome of `git switch-branch` or `git checkout`.
 
 It is also run after linkgit:git-clone[1], unless the `--no-checkout` (`-n`) option is
 used. The first parameter given to the hook is the null-ref, the second the

@@ -402,7 +402,8 @@ exit with a zero status.
 For example, the hook can simply run `git read-tree -u -m HEAD "$1"`
 in order to emulate `git fetch` that is run in the reverse direction
 with `git push`, as the two-tree form of `git read-tree -u -m` is
-essentially the same as `git checkout` that switches branches while
+essentially the same as `git switch-branch` or `git checkout`
+that switches branches while
 keeping the local changes in the working tree that do not interfere
 with the difference between the branches.
 

Documentation/gittutorial-2.txt +1 -1

index e0976f6017..125213d951 100644
@@ -376,7 +376,7 @@ Changes to be committed:
 
 Changes not staged for commit:
   (use "git add <file>..." to update what will be committed)
-  (use "git checkout -- <file>..." to discard changes in working directory)
+  (use "git checkout-files -- <file>..." to discard changes in working directory)
 
 	modified:   file.txt
 

Documentation/gittutorial.txt +2 -2

index 242de31cb6..396e55c191 100644
@@ -207,7 +207,7 @@ automatically.  The asterisk marks the branch you are currently on;
 type
 
 ------------------------------------------------
-$ git checkout experimental
+$ git switch-branch experimental
 ------------------------------------------------
 
 to switch to the experimental branch.  Now edit a file, commit the

@@ -216,7 +216,7 @@ change, and switch back to the master branch:
 ------------------------------------------------
 (edit file)
 $ git commit -a
-$ git checkout master
+$ git switch-branch master
 ------------------------------------------------
 
 Check that the change you made is no longer visible, since it was

Documentation/revisions.txt +1 -1

index 72daa20e76..f55502cd50 100644
@@ -115,7 +115,7 @@ Here's an example to make it more clear:
 ------------------------------
 $ git config push.default current
 $ git config remote.pushdefault myfork
-$ git checkout -b mybranch origin/master
+$ git switch-branch -b mybranch origin/master
 
 $ git rev-parse --symbolic-full-name @{upstream}
 refs/remotes/origin/master

Documentation/user-manual.txt +27 -27

index eff7890274..56397e93d4 100644
@@ -125,7 +125,7 @@ Create a new branch head pointing to one of these versions and check it
 out using linkgit:git-checkout[1]:
 
 ------------------------------------------------
-$ git checkout -b new v2.6.13
+$ git switch-branch -b new v2.6.13
 ------------------------------------------------
 
 The working directory then reflects the contents that the project had

@@ -282,10 +282,10 @@ a summary of the commands:
 	this command will fail with a warning.
 `git branch -D <branch>`::
 	delete the branch `<branch>` irrespective of its merged status.
-`git checkout <branch>`::
+`git switch-branch <branch>`::
 	make the current branch `<branch>`, updating the working
 	directory to reflect the version referenced by `<branch>`.
-`git checkout -b <new> <start-point>`::
+`git switch-branch -b <new> <start-point>`::
 	create a new branch `<new>` referencing `<start-point>`, and
 	check it out.
 

@@ -302,12 +302,12 @@ ref: refs/heads/master
 Examining an old version without creating a new branch
 ------------------------------------------------------
 
-The `git checkout` command normally expects a branch head, but will also
+The `git switch-branch` command normally expects a branch head, but will also
 accept an arbitrary commit; for example, you can check out the commit
 referenced by a tag:
 
 ------------------------------------------------
-$ git checkout v2.6.17
+$ git switch-branch v2.6.17
 Note: checking out 'v2.6.17'.
 
 You are in 'detached HEAD' state. You can look around, make experimental

@@ -317,7 +317,7 @@ state without impacting any branches by performing another checkout.
 If you want to create a new branch to retain commits you create, you may
 do so (now or later) by using -b with the checkout command again. Example:
 
-  git checkout -b new_branch_name
+  git switch-branch -b new_branch_name
 
 HEAD is now at 427abfa Linux v2.6.17
 ------------------------------------------------

@@ -373,7 +373,7 @@ You might want to build on one of these remote-tracking branches
 on a branch of your own, just as you would for a tag:
 
 ------------------------------------------------
-$ git checkout -b my-todo-copy origin/todo
+$ git switch-branch -b my-todo-copy origin/todo
 ------------------------------------------------
 
 You can also check out `origin/todo` directly to examine it or

@@ -1523,12 +1523,12 @@ Checking out an old version of a file
 
 In the process of undoing a previous bad change, you may find it
 useful to check out an older version of a particular file using
-linkgit:git-checkout[1].  We've used `git checkout` before to switch
+linkgit:git-checkout[1].  We've used `git switch-branch` before to switch
 branches, but it has quite different behavior if it is given a path
 name: the command
 
 -------------------------------------------------
-$ git checkout HEAD^ path/to/file
+$ git checkout-files HEAD^ path/to/file
 -------------------------------------------------
 
 replaces path/to/file by the contents it had in the commit HEAD^, and

@@ -2211,8 +2211,8 @@ $ git branch --track release origin/master
 These can be easily kept up to date using linkgit:git-pull[1].
 
 -------------------------------------------------
-$ git checkout test && git pull
-$ git checkout release && git pull
+$ git switch-branch test && git pull
+$ git switch-branch release && git pull
 -------------------------------------------------
 
 Important note!  If you have any local changes in these branches, then

@@ -2264,7 +2264,7 @@ tested changes
 2) help future bug hunters that use `git bisect` to find problems
 
 -------------------------------------------------
-$ git checkout -b speed-up-spinlocks v2.6.35
+$ git switch-branch -b speed-up-spinlocks v2.6.35
 -------------------------------------------------
 
 Now you apply the patch(es), run some tests, and commit the change(s).  If

@@ -2279,7 +2279,7 @@ When you are happy with the state of this change, you can merge it into the
 "test" branch in preparation to make it public:
 
 -------------------------------------------------
-$ git checkout test && git merge speed-up-spinlocks
+$ git switch-branch test && git merge speed-up-spinlocks
 -------------------------------------------------
 
 It is unlikely that you would have any conflicts here ... but you might if you

@@ -2291,7 +2291,7 @@ see the value of keeping each patch (or patch series) in its own branch.  It
 means that the patches can be moved into the `release` tree in any order.
 
 -------------------------------------------------
-$ git checkout release && git merge speed-up-spinlocks
+$ git switch-branch release && git merge speed-up-spinlocks
 -------------------------------------------------
 
 After a while, you will have a number of branches, and despite the

@@ -2358,7 +2358,7 @@ Here are some of the scripts that simplify all this even further.
 
 case "$1" in
 test|release)
-	git checkout $1 && git pull . origin
+	git switch-branch $1 && git pull . origin
 	;;
 origin)
 	before=$(git rev-parse refs/remotes/origin/master)

@@ -2400,7 +2400,7 @@ test|release)
 		echo $1 already merged into $2 1>&2
 		exit 1
 	fi
-	git checkout $2 && git pull . $1
+	git switch-branch $2 && git pull . $1
 	;;
 *)
 	usage

@@ -2512,7 +2512,7 @@ Suppose that you create a branch `mywork` on a remote-tracking branch
 `origin`, and create some commits on top of it:
 
 -------------------------------------------------
-$ git checkout -b mywork origin
+$ git switch-branch -b mywork origin
 $ vi file.txt
 $ git commit
 $ vi otherfile.txt

@@ -2552,7 +2552,7 @@ commits without any merges, you may instead choose to use
 linkgit:git-rebase[1]:
 
 -------------------------------------------------
-$ git checkout mywork
+$ git switch-branch mywork
 $ git rebase origin
 -------------------------------------------------
 

@@ -3668,13 +3668,13 @@ change within the submodule, and then update the superproject to reference the
 new commit:
 
 -------------------------------------------------
-$ git checkout master
+$ git switch-branch master
 -------------------------------------------------
 
 or
 
 -------------------------------------------------
-$ git checkout -b fix-up
+$ git switch-branch -b fix-up
 -------------------------------------------------
 
 then

@@ -4194,7 +4194,7 @@ start.
 A good place to start is with the contents of the initial commit, with:
 
 ----------------------------------------------------
-$ git checkout e83c5163
+$ git switch-branch e83c5163
 ----------------------------------------------------
 
 The initial revision lays the foundation for almost everything Git has

@@ -4437,10 +4437,10 @@ Managing branches
 -----------------
 
 -----------------------------------------------
-$ git branch	     # list all local branches in this repo
-$ git checkout test  # switch working directory to branch "test"
-$ git branch new     # create branch "new" starting at current HEAD
-$ git branch -d new  # delete branch "new"
+$ git branch			# list all local branches in this repo
+$ git switch-branch test	# switch working directory to branch "test"
+$ git branch new		# create branch "new" starting at current HEAD
+$ git branch -d new		# delete branch "new"
 -----------------------------------------------
 
 Instead of basing a new branch on current HEAD (the default), use:

@@ -4456,7 +4456,7 @@ $ git branch new test~10 # ten commits before tip of branch "test"
 Create and switch to a new branch at the same time:
 
 -----------------------------------------------
-$ git checkout -b new v2.6.15
+$ git switch-branch -b new v2.6.15
 -----------------------------------------------
 
 Update and examine branches from the repository you cloned from:

@@ -4467,7 +4467,7 @@ $ git branch -r		# list
   origin/master
   origin/next
...
-$ git checkout -b masterwork origin/master
+$ git switch-branch -b masterwork origin/master
 -----------------------------------------------
 
 Fetch a branch from a different repository, and give it a new

advice.c +1 -1

index 5f35656409..1befdb2163 100644
@@ -195,7 +195,7 @@ void detach_advice(const char *new_name)
 	"state without impacting any branches by performing another checkout.\n\n"
 	"If you want to create a new branch to retain commits you create, you may\n"
 	"do so (now or later) by using -b with the checkout command again. Example:\n\n"
-	"  git checkout -b <new-branch-name>\n\n");
+	"  git branch <new-branch-name>\n\n");
 
 	fprintf(stderr, fmt, new_name);
 }

sha1-name.c +1 -1

index faa60f69e3..4e4e14a45c 100644
@@ -771,7 +771,7 @@ static int get_oid_basic(const char *str, int len, struct object_id *oid,
 	"because it will be ignored when you just specify 40-hex. These refs\n"
 	"may be created by mistake. For example,\n"
 	"\n"
-	"  git checkout -b $br $(git rev-parse ...)\n"
+	"  git switch-branch -b $br $(git rev-parse ...)\n"
 	"\n"
 	"where \"$br\" is somehow empty and a 40-hex ref is created. Please\n"
 	"examine these refs and maybe delete them. Turn this message off by\n"

wt-status.c +1 -1

index a24711374c..6266683926 100644
@@ -224,7 +224,7 @@ static void wt_longstatus_print_dirty_header(struct wt_status *s,
 		status_printf_ln(s, c, _("  (use \"git add <file>...\" to update what will be committed)"));
 	else
 		status_printf_ln(s, c, _("  (use \"git add/rm <file>...\" to update what will be committed)"));
-	status_printf_ln(s, c, _("  (use \"git checkout -- <file>...\" to discard changes in working directory)"));
+	status_printf_ln(s, c, _("  (use \"git checkout-files <file>...\" to discard changes in working directory)"));
 	if (has_dirty_submodules)
 		status_printf_ln(s, c, _("  (commit or discard the untracked or modified content in submodules)"));
 	status_printf_ln(s, c, "%s", "");

Quoted 8 lines · Nguyễn Thái Ngọc Duy

There is currently no caller that calls this function with "a" being NULL. But it will be introduced shortly. It is used to construct the option array from scratch, e.g.

   struct parse_options opts = NULL;
   opts = parse_options_concat(opts, opts_1);
   opts = parse_options_concat(opts, opts_2);

While this addresses the immediate needs, I'd prefer to think about the API exposure of parse_options_concat, (related: do we want to have docs in its header file?) and I'd recommend to make it symmetrical, i.e. allow the second argument to also be NULL?

Quoted 2 lines · Nguyễn Thái Ngọc Duy

The good old "git checkout" command is still here and will be until all (or most of users) are sick of it.

Two comments on the goal (the implementation looked reasonable assuming the reader agrees with the gaol).

At least to me, the verb "switch" needs two things to switch between, i.e. "switch A and B", unless it is "switch to X". Either "switch-to-branch" or simply "switch-to", perhaps?

As I already hinted in my response to Stefan (?) about checkout-from-tree vs checkout-from-index, a command with multiple modes of operation is not confusing to people with the right mental model, and I suspect that having two separate commands for "checking out a branch" and "checking out paths" that is done by this step would help users to form the right mental model.

So I tend to think
these two are "training wheels", and suspect that once they got it, nobody will become "sick of" the single "checkout" command that can be used to do either. It's just the matter of being aware what can be done (which requires the right mental model) and how to tell Git what the user wants it do (two separate commands, operating mode option, or just the implied command line syntax---once the user knows what s/he is doing, these do not make that much a difference).

Quoted 2 lines · Nguyễn Thái Ngọc Duy

The assumption made is here

Quoted 4 lines

- "git checkout" is a horrible monster that should only be touched with a two-meter pole

- there are other commands that can achieve the same thing

Thanks for clearly spelling out the assumptions. It is good that this step cames at the end, as the earlier 6 steps looked reasonable to me.

Quoted 13 lines · Junio C Hamano

Quoted 2 lines · Nguyễn Thái Ngọc Duy

The good old "git checkout" command is still here and will be until all (or most of users) are sick of it.

Two comments on the goal (the implementation looked reasonable assuming the reader agrees with the gaol).

At least to me, the verb "switch" needs two things to switch between, i.e. "switch A and B", unless it is "switch to X". Either "switch-to-branch" or simply "switch-to", perhaps?

Quoted 6 lines

As I already hinted in my response to Stefan (?) about checkout-from-tree vs checkout-from-index, a command with multiple modes of operation is not confusing to people with the right mental model, and I suspect that having two separate commands for "checking out a branch" and "checking out paths" that is done by this step would help users to form the right mental model.

Since the other one is already "checkout-files", maybe this one could just be "checkout-branch".

Quoted 22 lines · Duy Nguyen

Quoted 13 lines · Junio C Hamano

Quoted 2 lines · Nguyễn Thái Ngọc Duy

The good old "git checkout" command is still here and will be until all (or most of users) are sick of it.

Two comments on the goal (the implementation looked reasonable assuming the reader agrees with the gaol).

At least to me, the verb "switch" needs two things to switch between, i.e. "switch A and B", unless it is "switch to X". Either "switch-to-branch" or simply "switch-to", perhaps?

Quoted 6 lines

As I already hinted in my response to Stefan (?) about checkout-from-tree vs checkout-from-index, a command with multiple modes of operation is not confusing to people with the right mental model, and I suspect that having two separate commands for "checking out a branch" and "checking out paths" that is done by this step would help users to form the right mental model.

Quoted 2 lines

Since the other one is already "checkout-files", maybe this one could just be "checkout-branch".

I dislike the checkout-* names, as we already have checkout-index as plumbing, so it would be confusing as to which checkout-* command should be used when and why as it seems the co-index moves content *from index* to the working tree, but the co-files moves content *to files*, whereas checkout-branch is neither 'moving' to or from a branch but rather 'switching' to that branch.

v2 is just a bit better to look at than v1. This is by no means final. If you think the command name is bad, the default behavior should change, or something else, speak up. It's still very "RFC".

v2 breaks down the giant patch in v1 and starts adding some changes in these new commands:

- restore-paths is renamed to checkout-paths. I wrote I didn't like "checkout" because of completion conflict. But who am I kidding, I'll use aliases anyway. "-files" instead of "-paths" because we already have ls-files.
- both commands will not accept no arguments. There is no "git checkout" equivalent.
- ambiguation rules are now aware that "switch-branch" for example can't take pathspec...

should we do
something about detached HEAD in this switch-branch command (or whatever its name will be)?

This is usually a confusing concept to new users

Quoted 5 lines · Duy Nguyen

should we do
something about detached HEAD in this switch-branch command (or whatever its name will be)?

This is usually a confusing concept to new users

And it just occurred to me that perhaps we should call this "unnamed branch" (at least at high UI level) instead of detached HEAD. It is technically not as accurate, but much better to understand.

I think users have problems with detached heads for several reasons:

1. Users often enter the detached head state unexpectedly (for example, by mistyping a "checkout" command or not understanding its multipurpose nature, or as a side-effect of running a submodule command). The change described here will go in the right direction towards addressing this, since you won't be able to accidentally detach your head by mistyping checkout. If detaching was always an intentional action by the user, it would be much less intimidating.

2. Git shows a lot of scary error messages when running in a detached head state. They tell you you're doing something dangerous, which dissuades users from experimenting with the feature. IMO, it would be better to replace the scary warning messages with instructions on where to get more information about detached heads (and those instructions should frontload info on how to reattach to a branch and how to recover commits from the reflog).

3. When in a detached head state, a lot of commands add extra confirmation prompts, which are unnecessary and intimidating.

Basically, the current user interface implies to the user that a detached head is an error condition they'll need to recover from rather than the normal and useful mode of working that it is.

- Stefan

Quoted 29 lines · Duy Nguyen

Quoted 8 lines · Nguyễn Thái Ngọc Duy

v2 is just a bit better to look at than v1. This is by no means final. If you think the command name is bad, the default behavior should change, or something else, speak up. It's still very "RFC".

v2 breaks down the giant patch in v1 and starts adding some changes in these new commands:

Quoted 8 lines

- restore-paths is renamed to checkout-paths. I wrote I didn't like "checkout" because of completion conflict. But who am I kidding, I'll use aliases anyway. "-files" instead of "-paths" because we already have ls-files.
- both commands will not accept no arguments. There is no "git checkout" equivalent.
- ambiguation rules are now aware that "switch-branch" for example can't take pathspec...

Another thing. Since we start with a clean slate, should we do something about detached HEAD in this switch-branch command (or whatever its name will be)?

This is usually a confusing concept to new users and I've seen some users have a hard time getting out of it. I'm too comfortable with detached HEAD to see this from new user's perspective and a better way to deal with it.
--
Duy

Since the other one is already "checkout-files", maybe this one could just be "checkout-branch".

nobody will become "sick of" the single "checkout" command that can

Quoted 13 lines · Junio C Hamano

Quoted 2 lines · Nguyễn Thái Ngọc Duy

The good old "git checkout" command is still here and will be until all (or most of users) are sick of it.

Two comments on the goal (the implementation looked reasonable assuming the reader agrees with the gaol).

At least to me, the verb "switch" needs two things to switch between, i.e. "switch A and B", unless it is "switch to X". Either "switch-to-branch" or simply "switch-to", perhaps?

Quoted 6 lines

As I already hinted in my response to Stefan (?) about checkout-from-tree vs checkout-from-index, a command with multiple modes of operation is not confusing to people with the right mental model, and I suspect that having two separate commands for "checking out a branch" and "checking out paths" that is done by this step would help users to form the right mental model.

Since the other one is already "checkout-files", maybe this one could just be "checkout-branch".

Quoted 8 lines

So I tend to think
these two are "training wheels", and suspect that once they got it, nobody will become "sick of" the single "checkout" command that can be used to do either. It's just the matter of being aware what can be done (which requires the right mental model) and how to tell Git what the user wants it do (two separate commands, operating mode option, or just the implied command line syntax---once the user knows what s/he is doing, these do not make that much a difference).

I would hope this becomes better defaults and being used 90% of time. Even though I know "git checkout" quite well, it still bites me from time to time. Having the right mental model is one thing. Having to think a bit every time to write "git checkout" with the right syntax, and whether you need "--" (that ambiguation problem can still bite you from time to time), is frankly something I'd rather avoid. --
Duy

Quoted 2 lines

Since the other one is already "checkout-files", maybe this one could just be "checkout-branch".

I rather like switch-branch and dislike the word "checkout" since it has been overloaded in git for so long (does it mean moving HEAD or copying files to my working tree?)

Quoted 1 line

nobody will become "sick of" the single "checkout" command that can

I have to admit I'm already sick of the checkout command. :-p I can see myself using these two new commands 100% of the time and never missing the old one.

Some behaviors I'd expect to see from these commands (I haven't yet checked to see if you've already done this):

git checkout-files <tree-ish>
should reset all the files in the repository regardless of the current directory - it should produce the same effect as "git reset --hard <tree-ish> && git reset HEAD@{1}". It should also delete locally-created files that aren't present in <tree-ish>, such that the final working tree is exactly identical to what was committed in that tree-ish.

git checkout-files foo -- myfile.txt
should delete myfile.txt if it is present locally but not present in foo.

git checkout-files foo -- .
should recursively checkout all files in the current folder and all subfolders, and delete any locally-created files if they're not present in foo.

git checkout-files should never move HEAD in any circumstance.

Suggestion:
If git checkout-files overwrites or deletes any locally-modified files from the workspace or index, those files could be auto-stashed. That would make it easy to restore them in the event of a mistyped command. Auto-stashing could be suppressed with a command-line argument (with alternate behaviors being fail-if-modified or always-overwrite).

Idea:
If git checkout-files modifies the submodules file, it could also auto-update the submodules. (For example, with something like "git submodule update --init --recursive --progress").

- Stefan

Quoted 42 lines · Duy Nguyen

Quoted 13 lines · Junio C Hamano

Quoted 2 lines · Nguyễn Thái Ngọc Duy

The good old "git checkout" command is still here and will be until all (or most of users) are sick of it.

Two comments on the goal (the implementation looked reasonable assuming the reader agrees with the gaol).

At least to me, the verb "switch" needs two things to switch between, i.e. "switch A and B", unless it is "switch to X". Either "switch-to-branch" or simply "switch-to", perhaps?

Quoted 6 lines

As I already hinted in my response to Stefan (?) about checkout-from-tree vs checkout-from-index, a command with multiple modes of operation is not confusing to people with the right mental model, and I suspect that having two separate commands for "checking out a branch" and "checking out paths" that is done by this step would help users to form the right mental model.

Since the other one is already "checkout-files", maybe this one could just be "checkout-branch".

Quoted 8 lines

So I tend to think
these two are "training wheels", and suspect that once they got it, nobody will become "sick of" the single "checkout" command that can be used to do either. It's just the matter of being aware what can be done (which requires the right mental model) and how to tell Git what the user wants it do (two separate commands, operating mode option, or just the implied command line syntax---once the user knows what s/he is doing, these do not make that much a difference).

I would hope this becomes better defaults and being used 90% of time. Even though I know "git checkout" quite well, it still bites me from time to time. Having the right mental model is one thing. Having to think a bit every time to write "git checkout" with the right syntax, and whether you need "--" (that ambiguation problem can still bite you from time to time), is frankly something I'd rather avoid. --
Duy

Although I have no problem with "switch-branch" as a command name, some alternative names we might consider for switch-branch might be:

chbranch
swbranch
switch
branch change (as a subcommand for the "branch" command)

I've personally been using "chbranch" as an alias for this functionality for some time.

- Stefan

Quoted 90 lines · Stefan Xenos

Quoted 2 lines

Since the other one is already "checkout-files", maybe this one could just be "checkout-branch".

I rather like switch-branch and dislike the word "checkout" since it has been overloaded in git for so long (does it mean moving HEAD or copying files to my working tree?)

Quoted 1 line

nobody will become "sick of" the single "checkout" command that can

I have to admit I'm already sick of the checkout command. :-p I can see myself using these two new commands 100% of the time and never missing the old one.

Some behaviors I'd expect to see from these commands (I haven't yet checked to see if you've already done this):

git checkout-files <tree-ish>
should reset all the files in the repository regardless of the current directory - it should produce the same effect as "git reset --hard <tree-ish> && git reset HEAD@{1}". It should also delete locally-created files that aren't present in <tree-ish>, such that the final working tree is exactly identical to what was committed in that tree-ish.

git checkout-files foo -- myfile.txt
should delete myfile.txt if it is present locally but not present in foo.

git checkout-files foo -- .
should recursively checkout all files in the current folder and all subfolders, and delete any locally-created files if they're not present in foo.

git checkout-files should never move HEAD in any circumstance.

Suggestion:
If git checkout-files overwrites or deletes any locally-modified files from the workspace or index, those files could be auto-stashed. That would make it easy to restore them in the event of a mistyped command. Auto-stashing could be suppressed with a command-line argument (with alternate behaviors being fail-if-modified or always-overwrite).

Idea:
If git checkout-files modifies the submodules file, it could also auto-update the submodules. (For example, with something like "git submodule update --init --recursive --progress").

- Stefan

Quoted 42 lines · Duy Nguyen

Quoted 13 lines · Junio C Hamano

Quoted 2 lines · Nguyễn Thái Ngọc Duy

The good old "git checkout" command is still here and will be until all (or most of users) are sick of it.

Two comments on the goal (the implementation looked reasonable assuming the reader agrees with the gaol).

At least to me, the verb "switch" needs two things to switch between, i.e. "switch A and B", unless it is "switch to X". Either "switch-to-branch" or simply "switch-to", perhaps?

Quoted 6 lines

As I already hinted in my response to Stefan (?) about checkout-from-tree vs checkout-from-index, a command with multiple modes of operation is not confusing to people with the right mental model, and I suspect that having two separate commands for "checking out a branch" and "checking out paths" that is done by this step would help users to form the right mental model.

Since the other one is already "checkout-files", maybe this one could just be "checkout-branch".

Quoted 8 lines

So I tend to think
these two are "training wheels", and suspect that once they got it, nobody will become "sick of" the single "checkout" command that can be used to do either. It's just the matter of being aware what can be done (which requires the right mental model) and how to tell Git what the user wants it do (two separate commands, operating mode option, or just the implied command line syntax---once the user knows what s/he is doing, these do not make that much a difference).

I would hope this becomes better defaults and being used 90% of time. Even though I know "git checkout" quite well, it still bites me from time to time. Having the right mental model is one thing. Having to think a bit every time to write "git checkout" with the right syntax, and whether you need "--" (that ambiguation problem can still bite you from time to time), is frankly something I'd rather avoid. --
Duy

I dislike the checkout-* names, as we already have checkout-index as plumbing, so it would be confusing as to which checkout-* command should be used when and why as it seems the co-index moves content *from index* to the working tree, but the co-files moves content *to files*, whereas checkout-branch is neither 'moving' to or from a branch but rather 'switching' to that branch.

Although I have no problem with "switch-branch" as a command name, some alternative names we might consider for switch-branch might be:

chbranch
swbranch

switch
branch change (as a subcommand for the "branch" command)

I see my deliberate attempt to provoke has failed :D Giving your view of the new commands as "training wheels", I take it we still should make them visible as much as possible, but we just not try to hide "git checkout" as much (e.g. we mention both new and old commands, instead of just mentioning the new one, when suggesting something)?

So - IMO - detaching should always be an explicit action. Some options that occur to me:

git switch-branch --detach

git detach

git switch-branch HEAD

Quoted 6 lines · Duy Nguyen

Quoted 4 lines · Duy Nguyen

should we do
something about detached HEAD in this switch-branch command (or whatever its name will be)?

Quoted 5 lines

Quoted 1 line

This is usually a confusing concept to new users

And it just occurred to me that perhaps we should call this "unnamed branch" (at least at high UI level) instead of detached HEAD. It is technically not as accurate, but much better to understand.

or 'direct' branch?

I mean 'detached HEAD' itself is also not correct
as the HEAD points to a valid commit/tag usually, so it is attached to that content. The detachment comes from the implicit "from a branch".

Quoted 5 lines · Stefan Xenos

Although I have no problem with "switch-branch" as a command name, some alternative names we might consider for switch-branch might be:

chbranch
swbranch

Please never go in that direction. So far, we made a conscious effort to keep the names of most frequently used subcommand to proper words that can be understood by coders (IOW, I expect they know what 'grep' is, even though that may not be a 'proper word').

Quoted 2 lines

switch
branch change (as a subcommand for the "branch" command)

It is more like moving to the branch to work on. I think 'switch' is something SVN veterans may find familiar. Both are much better than ch/swbranch that are overly cryptic.

Some behaviors I'd expect to see from these commands (I haven't yet checked to see if you've already done this):

git checkout-files <tree-ish>
should reset all the files in the repository regardless of the current directory - it should produce the same effect as "git reset --hard <tree-ish> && git reset HEAD@{1}". It should also delete locally-created files that aren't present in <tree-ish>, such that the final working tree is exactly identical to what was committed in that tree-ish.

git checkout-files foo -- myfile.txt
should delete myfile.txt if it is present locally but not present in foo.

git checkout-files foo -- .
should recursively checkout all files in the current folder and all subfolders, and delete any locally-created files if they're not present in foo.

Suggestion:
If git checkout-files overwrites or deletes any locally-modified files from the workspace or index, those files could be auto-stashed. That would make it easy to restore them in the event of a mistyped command. Auto-stashing could be suppressed with a command-line argument (with alternate behaviors being fail-if-modified or always-overwrite).

Idea:
If git checkout-files modifies the submodules file, it could also auto-update the submodules. (For example, with something like "git submodule update --init --recursive --progress").