git/list[1] front-page[2] threads[3] people[4] search[5] about
 

[PATCH v3] checkout: add --fetch to fetch remote before resolving start-point

From
Harald Nordgren via GitGitGadget <gitgitgadget@gmail.com>
Date
Apr 26, 2026, 07:24 UTC
Message-ID
<pull.2281.v3.git.git.1777188295021.gitgitgadget@gmail.com>
In-Reply-To
<pull.2281.v2.git.git.1777140755373.gitgitgadget@gmail.com>
From: Harald Nordgren <haraldnordgren@gmail.com>
A common workflow is:
    git fetch origin
    git checkout -b new_branch origin/some-branch

The first command exists purely so the second sees an up-to-date view of the remote. If it is forgotten, origin/some-branch points at a stale commit and the new local branch is created from the wrong start point.

Teach checkout (and switch) a --fetch flag that folds the two steps into one:

    git checkout --fetch -b new_branch origin/some-branch

When --fetch is given and <start-point> is in <remote>/<branch> form, run "git fetch <remote> <branch>" before resolving the ref. This narrows the fetch to the requested branch so that other remote-tracking branches are left untouched -- many tools rely on the stability of remote-tracking refs between explicit fetches. If <start-point> is a bare remote name like "origin" (which resolves to that remote's default branch), "git fetch <remote>" is run instead, since the target branch is not known up front. Abort the checkout if the fetch fails.

Also add a checkout.fetch config to enable this by default.
Signed-off-by: Harald Nordgren <haraldnordgren@gmail.com>
---
    checkout: add --fetch to fetch remote before resolving start-point
    
    When <start-point> is in <remote>/<branch> form, only fetch that one
    branch instead of the whole remote, so unrelated remote-tracking
    branches stay stable. The bare-remote form (e.g. "origin") still fetches
    everything.
Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-git-2281%2FHaraldNordgren%2Fcheckout-fetch-start-point-v3
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-git-2281/HaraldNordgren/checkout-fetch-start-point-v3
Pull-Request: https://github.com/git/git/pull/2281
Range-diff vs v2:
 1:  13074c9fea ! 1:  df7b63862c checkout: add --fetch to fetch remote before resolving start-point
     @@ Commit message
      
              git checkout --fetch -b new_branch origin/some-branch
      
     -    When --fetch is given and <start-point> names a configured remote
     -    (either bare, like "origin", or prefixed, like "origin/foo"), fetch
     -    that remote before resolving the ref. Abort the checkout if the fetch
     -    fails.
     +    When --fetch is given and <start-point> is in <remote>/<branch> form,
     +    run "git fetch <remote> <branch>" before resolving the ref. This
     +    narrows the fetch to the requested branch so that other
     +    remote-tracking branches are left untouched -- many tools rely on the
     +    stability of remote-tracking refs between explicit fetches. If
     +    <start-point> is a bare remote name like "origin" (which resolves to
     +    that remote's default branch), "git fetch <remote>" is run instead,
     +    since the target branch is not known up front. Abort the checkout if
     +    the fetch fails.
      
          Also add a checkout.fetch config to enable this by default.
      
     @@ Documentation/git-checkout.adoc: linkgit:git-config[1].
       
      +`--fetch`::
      +`--no-fetch`::
     -+	If _<start-point>_ names a configured remote -- either bare,
     -+	like `origin` (which resolves to the remote's default branch),
     -+	or in _<remote>/<branch>_ form -- run `git fetch` on that
     -+	remote before resolving _<start-point>_. If the fetch fails,
     -+	the checkout is aborted and no local branch is created.
     ++	If _<start-point>_ refers to a remote-tracking branch, fetch
     ++	from that remote before resolving it. When _<start-point>_ is
     ++	in _<remote>/<branch>_ form, only that branch is updated; when
     ++	it is a bare remote name (e.g. `origin`), the whole remote is
     ++	fetched. If the fetch fails, the checkout is aborted.
      ++
      +The default behavior can be set via the `checkout.fetch` configuration
      +variable.
     @@ Documentation/git-switch.adoc: ambiguous but exists on the 'origin' remote. See
       
      +`--fetch`::
      +`--no-fetch`::
     -+	If _<start-point>_ names a configured remote -- either bare,
     -+	like `origin` (which resolves to the remote's default branch),
     -+	or in _<remote>/<branch>_ form -- run `git fetch` on that
     -+	remote before resolving _<start-point>_. If the fetch fails,
     -+	the switch is aborted and no local branch is created.
     ++	If _<start-point>_ refers to a remote-tracking branch, fetch
     ++	from that remote before resolving it. When _<start-point>_ is
     ++	in _<remote>/<branch>_ form, only that branch is updated; when
     ++	it is a bare remote name (e.g. `origin`), the whole remote is
     ++	fetched. If the fetch fails, the switch is aborted.
      ++
      +The default behavior can be set via the `checkout.fetch` configuration
      +variable.
     @@ builtin/checkout.c: struct branch_info {
      +	}
      +
      +	strvec_pushl(&cmd.args, "fetch", remote_name, NULL);
     ++	if (slash && slash[1])
     ++		strvec_push(&cmd.args, slash + 1);
      +	cmd.git_cmd = 1;
      +	free(remote_name);
      +	if (run_command(&cmd))
     @@ t/t7201-co.sh: test_expect_success 'tracking info copied with autoSetupMerge=inh
      +	test_cmp_rev refs/remotes/fetch_upstream/fetch_new HEAD
      +'
      +
     ++test_expect_success 'checkout --fetch <remote>/<branch> leaves other tracking branches untouched' '
     ++	git checkout main &&
     ++	git -C fetch_upstream checkout -b fetch_target &&
     ++	test_commit -C fetch_upstream u_target_pre &&
     ++	git -C fetch_upstream checkout -b fetch_other &&
     ++	test_commit -C fetch_upstream u_other_pre &&
     ++	git fetch fetch_upstream &&
     ++	other_before=$(git rev-parse refs/remotes/fetch_upstream/fetch_other) &&
     ++	git -C fetch_upstream checkout fetch_target &&
     ++	test_commit -C fetch_upstream u_target_post &&
     ++	git -C fetch_upstream checkout fetch_other &&
     ++	test_commit -C fetch_upstream u_other_post &&
     ++	git checkout --fetch -b local_target fetch_upstream/fetch_target &&
     ++	test_cmp_rev refs/remotes/fetch_upstream/fetch_target HEAD &&
     ++	test "$(git rev-parse refs/remotes/fetch_upstream/fetch_other)" = "$other_before"
     ++'
     ++
      +test_expect_success 'checkout --fetch with bare remote name fetches the remote' '
      +	git checkout main &&
      +	git -C fetch_upstream checkout -b fetch_new2 &&
 Documentation/config/checkout.adoc |  5 +++
 Documentation/git-checkout.adoc    | 11 +++++
 Documentation/git-switch.adoc      | 11 +++++
 builtin/checkout.c                 | 50 +++++++++++++++++++++-
 t/t7201-co.sh                      | 68 ++++++++++++++++++++++++++++++
 t/t9902-completion.sh              |  1 +
 6 files changed, 144 insertions(+), 2 deletions(-)
diff --git a/Documentation/config/checkout.adoc b/Documentation/config/checkout.adoc
index e35d212969..c95f72b38e 100644
--- a/Documentation/config/checkout.adoc
+++ b/Documentation/config/checkout.adoc
@@ -22,6 +22,11 @@ commands or functionality in the future.
 	option in `git checkout` and `git switch`. See
 	linkgit:git-switch[1] and linkgit:git-checkout[1].
 
+`checkout.fetch`::
+	Provides the default value for the `--fetch` or `--no-fetch`
+	option in `git checkout` and `git switch`. See
+	linkgit:git-switch[1] and linkgit:git-checkout[1].
+
 `checkout.workers`::
 	The number of parallel workers to use when updating the working tree.
 	The default is one, i.e. sequential execution. If set to a value less
diff --git a/Documentation/git-checkout.adoc b/Documentation/git-checkout.adoc
index 43ccf47cf6..f5cc1ced74 100644
--- a/Documentation/git-checkout.adoc
+++ b/Documentation/git-checkout.adoc
@@ -201,6 +201,17 @@ linkgit:git-config[1].
 The default behavior can be set via the `checkout.guess` configuration
 variable.
 
+`--fetch`::
+`--no-fetch`::
+	If _<start-point>_ refers to a remote-tracking branch, fetch
+	from that remote before resolving it. When _<start-point>_ is
+	in _<remote>/<branch>_ form, only that branch is updated; when
+	it is a bare remote name (e.g. `origin`), the whole remote is
+	fetched. If the fetch fails, the checkout is aborted.
++
+The default behavior can be set via the `checkout.fetch` configuration
+variable.
+
 `-l`::
 	Create the new branch's reflog; see linkgit:git-branch[1] for
 	details.
diff --git a/Documentation/git-switch.adoc b/Documentation/git-switch.adoc
index 87707e9265..29743bafea 100644
--- a/Documentation/git-switch.adoc
+++ b/Documentation/git-switch.adoc
@@ -110,6 +110,17 @@ ambiguous but exists on the 'origin' remote. See also
 The default behavior can be set via the `checkout.guess` configuration
 variable.
 
+`--fetch`::
+`--no-fetch`::
+	If _<start-point>_ refers to a remote-tracking branch, fetch
+	from that remote before resolving it. When _<start-point>_ is
+	in _<remote>/<branch>_ form, only that branch is updated; when
+	it is a bare remote name (e.g. `origin`), the whole remote is
+	fetched. If the fetch fails, the switch is aborted.
++
+The default behavior can be set via the `checkout.fetch` configuration
+variable.
+
 `-f`::
 `--force`::
 	An alias for `--discard-changes`.
diff --git a/builtin/checkout.c b/builtin/checkout.c
index e031e61886..8d810fe2fa 100644
--- a/builtin/checkout.c
+++ b/builtin/checkout.c
@@ -30,7 +30,9 @@
 #include "repo-settings.h"
 #include "resolve-undo.h"
 #include "revision.h"
+#include "run-command.h"
 #include "setup.h"
+#include "strvec.h"
 #include "submodule.h"
 #include "symlinks.h"
 #include "trace2.h"
@@ -61,6 +63,7 @@ struct checkout_opts {
 	int count_checkout_paths;
 	int overlay_mode;
 	int dwim_new_local_branch;
+	int fetch;
 	int discard_changes;
 	int accept_ref;
 	int accept_pathspec;
@@ -112,6 +115,36 @@ struct branch_info {
 	char *checkout;
 };
 
+static void fetch_remote_for_start_point(const char *arg)
+{
+	const char *slash;
+	char *remote_name;
+	struct remote *remote;
+	struct child_process cmd = CHILD_PROCESS_INIT;
+
+	if (!arg || !*arg)
+		return;
+
+	slash = strchr(arg, '/');
+	if (slash == arg)
+		return;
+	remote_name = slash ? xstrndup(arg, slash - arg) : xstrdup(arg);
+
+	remote = remote_get(remote_name);
+	if (!remote || !remote_is_configured(remote, 1)) {
+		free(remote_name);
+		return;
+	}
+
+	strvec_pushl(&cmd.args, "fetch", remote_name, NULL);
+	if (slash && slash[1])
+		strvec_push(&cmd.args, slash + 1);
+	cmd.git_cmd = 1;
+	free(remote_name);
+	if (run_command(&cmd))
+		die(_("failed to fetch start-point '%s'"), arg);
+}
+
 static void branch_info_release(struct branch_info *info)
 {
 	free(info->name);
@@ -1237,6 +1270,10 @@ static int git_checkout_config(const char *var, const char *value,
 		opts->dwim_new_local_branch = git_config_bool(var, value);
 		return 0;
 	}
+	if (!strcmp(var, "checkout.fetch")) {
+		opts->fetch = git_config_bool(var, value);
+		return 0;
+	}
 
 	if (starts_with(var, "submodule."))
 		return git_default_submodule_config(var, value, NULL);
@@ -1942,8 +1979,13 @@ static int checkout_main(int argc, const char **argv, const char *prefix,
 			opts->dwim_new_local_branch &&
 			opts->track == BRANCH_TRACK_UNSPECIFIED &&
 			!opts->new_branch;
-		int n = parse_branchname_arg(argc, argv, dwim_ok, which_command,
-					     &new_branch_info, opts, &rev);
+		int n;
+
+		if (opts->fetch)
+			fetch_remote_for_start_point(argv[0]);
+
+		n = parse_branchname_arg(argc, argv, dwim_ok, which_command,
+					 &new_branch_info, opts, &rev);
 		argv += n;
 		argc -= n;
 	} else if (!opts->accept_ref && opts->from_treeish) {
@@ -2052,6 +2094,8 @@ int cmd_checkout(int argc,
 		OPT_BOOL(0, "overlay", &opts.overlay_mode, N_("use overlay mode (default)")),
 		OPT_BOOL(0, "auto-advance", &opts.auto_advance,
 			 N_("auto advance to the next file when selecting hunks interactively")),
+		OPT_BOOL(0, "fetch", &opts.fetch,
+			 N_("fetch from the remote first if <start-point> is a remote-tracking branch")),
 		OPT_END()
 	};
 
@@ -2102,6 +2146,8 @@ int cmd_switch(int argc,
 			 N_("second guess 'git switch <no-such-branch>'")),
 		OPT_BOOL(0, "discard-changes", &opts.discard_changes,
 			 N_("throw away local modifications")),
+		OPT_BOOL(0, "fetch", &opts.fetch,
+			 N_("fetch from the remote first if <start-point> is a remote-tracking branch")),
 		OPT_END()
 	};
 
diff --git a/t/t7201-co.sh b/t/t7201-co.sh
index 9bcf7c0b40..cf2ceb4052 100755
--- a/t/t7201-co.sh
+++ b/t/t7201-co.sh
@@ -801,4 +801,72 @@ test_expect_success 'tracking info copied with autoSetupMerge=inherit' '
 	test_cmp_config "" --default "" branch.main2.merge
 '
 
+test_expect_success 'setup upstream for --fetch tests' '
+	git checkout main &&
+	git init fetch_upstream &&
+	test_commit -C fetch_upstream u_main &&
+	git remote add fetch_upstream fetch_upstream &&
+	git fetch fetch_upstream &&
+	git -C fetch_upstream checkout -b fetch_new &&
+	test_commit -C fetch_upstream u_new
+'
+
+test_expect_success 'checkout --fetch -b picks up branch created upstream after clone' '
+	git checkout main &&
+	test_must_fail git rev-parse --verify refs/remotes/fetch_upstream/fetch_new &&
+	git checkout --fetch -b local_new fetch_upstream/fetch_new &&
+	test_cmp_rev refs/remotes/fetch_upstream/fetch_new HEAD
+'
+
+test_expect_success 'checkout --fetch <remote>/<branch> leaves other tracking branches untouched' '
+	git checkout main &&
+	git -C fetch_upstream checkout -b fetch_target &&
+	test_commit -C fetch_upstream u_target_pre &&
+	git -C fetch_upstream checkout -b fetch_other &&
+	test_commit -C fetch_upstream u_other_pre &&
+	git fetch fetch_upstream &&
+	other_before=$(git rev-parse refs/remotes/fetch_upstream/fetch_other) &&
+	git -C fetch_upstream checkout fetch_target &&
+	test_commit -C fetch_upstream u_target_post &&
+	git -C fetch_upstream checkout fetch_other &&
+	test_commit -C fetch_upstream u_other_post &&
+	git checkout --fetch -b local_target fetch_upstream/fetch_target &&
+	test_cmp_rev refs/remotes/fetch_upstream/fetch_target HEAD &&
+	test "$(git rev-parse refs/remotes/fetch_upstream/fetch_other)" = "$other_before"
+'
+
+test_expect_success 'checkout --fetch with bare remote name fetches the remote' '
+	git checkout main &&
+	git -C fetch_upstream checkout -b fetch_new2 &&
+	test_commit -C fetch_upstream u_new2 &&
+	test_must_fail git rev-parse --verify refs/remotes/fetch_upstream/fetch_new2 &&
+	git checkout --fetch -b local_from_remote fetch_upstream &&
+	git rev-parse --verify refs/remotes/fetch_upstream/fetch_new2
+'
+
+test_expect_success 'checkout --fetch aborts and does not create branch on fetch failure' '
+	git checkout main &&
+	test_might_fail git branch -D bogus &&
+	test_must_fail git checkout --fetch -b bogus fetch_upstream/does_not_exist &&
+	test_must_fail git rev-parse --verify refs/heads/bogus
+'
+
+test_expect_success 'checkout.fetch=true enables fetching without --fetch' '
+	git checkout main &&
+	git -C fetch_upstream checkout -b fetch_cfg &&
+	test_commit -C fetch_upstream u_cfg &&
+	test_must_fail git rev-parse --verify refs/remotes/fetch_upstream/fetch_cfg &&
+	git -c checkout.fetch=true checkout -b local_cfg fetch_upstream/fetch_cfg &&
+	test_cmp_rev refs/remotes/fetch_upstream/fetch_cfg HEAD
+'
+
+test_expect_success 'switch --fetch -c picks up branch created upstream after clone' '
+	git checkout main &&
+	git -C fetch_upstream checkout -b fetch_switch &&
+	test_commit -C fetch_upstream u_switch &&
+	test_must_fail git rev-parse --verify refs/remotes/fetch_upstream/fetch_switch &&
+	git switch --fetch -c local_switch fetch_upstream/fetch_switch &&
+	test_cmp_rev refs/remotes/fetch_upstream/fetch_switch HEAD
+'
+
 test_done
diff --git a/t/t9902-completion.sh b/t/t9902-completion.sh
index 2f9a597ec7..dc1d63669f 100755
--- a/t/t9902-completion.sh
+++ b/t/t9902-completion.sh
@@ -2602,6 +2602,7 @@ test_expect_success 'double dash "git checkout"' '
 	--ignore-other-worktrees Z
 	--recurse-submodules Z
 	--auto-advance Z
+	--fetch Z
 	--progress Z
 	--guess Z
 	--no-guess Z

base-commit: 94f057755b7941b321fd11fec1b2e3ca5313a4e0

-- 
gitgitgadget
Previous: Harald Nordgren via GitGitGadgetNext: Ramsay Jones
Message 21 of 73 in “checkout: add --fetch to fetch remote before resolving start-point”
  1. checkout: add --fetch to fetch remote before resolving start-pointHarald Nordgren via GitGitGadget, Apr 24, 2026
  2. Ramsay JonesApr 24, 2026
  3. D. Ben KnobleApr 24, 2026
  4. Comments on Phillip's reviewHarald Nordgren, Apr 25, 2026
  5. Wrong subject lineHarald Nordgren, Apr 25, 2026
  6. Harald NordgrenJun 18, 2026
  7. D. Ben KnobleJun 18, 2026
  8. Kristoffer HaugsbakkApr 24, 2026
  9. Comments on Phillip's reviewHarald Nordgren, Apr 25, 2026
  10. Wrong subject lineHarald Nordgren, Apr 25, 2026
  11. Kristoffer HaugsbakkApr 26, 2026
  12. Harald NordgrenApr 26, 2026
  13. Marc BranchaudApr 24, 2026
  14. Wrong subject lineHarald Nordgren, Apr 25, 2026
  15. Junio C HamanoApr 24, 2026
  16. Junio C HamanoApr 25, 2026
  17. Multiple remotesHarald Nordgren, Apr 25, 2026
  18. Ben KnobleApr 25, 2026
  19. ghHarald Nordgren, Apr 25, 2026
  20. checkout: add --fetch to fetch remote before resolving start-pointHarald Nordgren via GitGitGadget, Apr 25, 2026
  21. checkout: add --fetch to fetch remote before resolving start-pointHarald Nordgren via GitGitGadget, Apr 26, 2026
  22. Ramsay JonesApr 26, 2026
  23. checkout: add --fetch to fetch remote before resolving start-pointHarald Nordgren via GitGitGadget, Apr 26, 2026
  24. Junio C HamanoApr 28, 2026
  25. Harald NordgrenApr 28, 2026
  26. checkout: extend --track with a "fetch" mode to refresh start-pointHarald Nordgren via GitGitGadget, Apr 28, 2026
  27. Junio C HamanoMay 3, 2026
  28. checkout: add --autostash option for branch switchingHarald Nordgren, May 3, 2026
  29. checkout: extend --track with a "fetch" mode to refresh start-pointHarald Nordgren via GitGitGadget, May 3, 2026
  30. checkout: extend --track with a "fetch" mode to refresh start-pointHarald Nordgren, May 7, 2026
  31. Phillip WoodMay 8, 2026
  32. checkout: add --fetch to fetch remote before resolving start-pointHarald Nordgren, May 8, 2026
  33. Harald NordgrenJun 18, 2026
  34. checkout: extend --track with a "fetch" mode to refresh start-pointHarald Nordgren via GitGitGadget, May 8, 2026
  35. Phillip WoodMay 11, 2026
  36. checkout: extend --track with a "fetch" mode to refresh start-pointHarald Nordgren via GitGitGadget, May 11, 2026
  37. Junio C HamanoMay 12, 2026
  38. Harald NordgrenMay 18, 2026
  39. checkout: extend --track with a "fetch" mode to refresh start-pointHarald Nordgren via GitGitGadget, May 12, 2026
  40. checkout: extend --track with a "fetch" mode to refresh start-pointHarald Nordgren via GitGitGadget, May 18, 2026
  41. Junio C HamanoMay 19, 2026
  42. Harald NordgrenMay 19, 2026
  43. Junio C HamanoMay 19, 2026
  44. Harald NordgrenMay 19, 2026
  45. Harald NordgrenMay 19, 2026
  46. checkout: extend --track with a "fetch" mode to refresh start-pointHarald Nordgren via GitGitGadget, May 19, 2026
  47. Junio C HamanoMay 19, 2026
  48. Phillip WoodMay 21, 2026
  49. Harald NordgrenMay 21, 2026
  50. Junio C HamanoMay 21, 2026
  51. Phillip WoodMay 21, 2026
  52. Junio C HamanoMay 21, 2026
  53. Harald NordgrenJun 13, 2026
  54. checkout: extend --track with a "fetch" mode to refresh start-pointHarald Nordgren via GitGitGadget, May 21, 2026
  55. 0/2 checkout: --track=fetchHarald Nordgren via GitGitGadget, May 23, 2026
  56. 1/2 branch: expose helpers for finding the remote owning a tracking refHarald Nordgren via GitGitGadget, May 23, 2026
  57. 2/2 checkout: extend --track with a "fetch" mode to refresh start-pointHarald Nordgren via GitGitGadget, May 23, 2026
  58. Junio C HamanoJun 17, 2026
  59. Harald NordgrenJun 17, 2026
  60. Junio C HamanoJun 18, 2026
  61. 0/2 checkout: --track=fetchHarald Nordgren via GitGitGadget, Jun 18, 2026
  62. 1/2 branch: expose helpers for finding the remote owning a tracking refHarald Nordgren via GitGitGadget, Jun 18, 2026
  63. 2/2 checkout: extend --track with a "fetch" mode to refresh start-pointHarald Nordgren via GitGitGadget, Jun 18, 2026
  64. Phillip WoodJun 23, 2026
  65. Harald NordgrenJun 23, 2026
  66. Junio C HamanoJun 24, 2026
  67. Ben KnobleJun 25, 2026
  68. Harald NordgrenJun 25, 2026
  69. Kristofer KarlssonJun 25, 2026
  70. 0/2 checkout: --track=fetchHarald Nordgren via GitGitGadget, Jun 24, 2026
  71. 1/2 branch: expose helpers for finding the remote owning a tracking refHarald Nordgren via GitGitGadget, Jun 24, 2026
  72. 2/2 checkout: extend --track with a "fetch" mode to refresh start-pointHarald Nordgren via GitGitGadget, Jun 24, 2026
  73. Junio C HamanoJul 23, 2026

Read the whole thread, see it on lore, or plain text.

$ cat FOOTERMessages come from the public archive at lore.kernel.org/git, fetched every hour. The front page is chosen and written each morning by an AI editor and can be wrong; the threads themselves are the record. About and API. For agents: an MCP server at https://gitlist.dev/mcp, and any thread, story or person page as Markdown by adding .md to its URL (or sending Accept: text/markdown). Details in /llms.txt.