# [PATCH] remote: add --set-head option to 'git remote add' 6 messages from 2026-04-25 to 2026-04-26. Participants: Harald Nordgren via GitGitGadget, Ben Knoble, Harald Nordgren, Junio C Hamano, Jeff King. Thread: https://gitlist.dev/t/65552 ## Harald Nordgren via GitGitGadget, 2026-04-25 11:19 Subject: [PATCH] remote: add --set-head option to 'git remote add' Message-ID: ``` From: Harald Nordgren Mirror the behavior 'git clone' applies to its first remote: after fetching, set refs/remotes//HEAD to the remote's default branch. Equivalent to running: git remote add -f git remote set-head -a The new option implies --fetch. Signed-off-by: Harald Nordgren --- remote: add --set-head option to 'git remote add' When using GitHub's gh tool to fork a repo, it seems that set-head isn't run on the upstream remote. So its default branch is not recorded locally, meaning that 'git log fork' will not work. With git remote add --set-head upstream , the default branch is set in the same step and things can work out of the box after a small change on 'gh' that I will do as a next step. Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-git-2283%2FHaraldNordgren%2Fset_head-v1 Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-git-2283/HaraldNordgren/set_head-v1 Pull-Request: https://github.com/git/git/pull/2283 Documentation/git-remote.adoc | 9 ++++++++- builtin/remote.c | 26 ++++++++++++++++++++++++-- t/t5505-remote.sh | 8 ++++++++ 3 files changed, 40 insertions(+), 3 deletions(-) diff --git a/Documentation/git-remote.adoc b/Documentation/git-remote.adoc index eaae30aa88..0ef49c4164 100644 --- a/Documentation/git-remote.adoc +++ b/Documentation/git-remote.adoc @@ -10,7 +10,7 @@ SYNOPSIS -------- [synopsis] git remote [-v | --verbose] -git remote add [-t ] [-m ] [-f] [--[no-]tags] [--mirror=(fetch|push)] +git remote add [-t ] [-m ] [-f] [--set-head] [--[no-]tags] [--mirror=(fetch|push)] git remote rename [--[no-]progress] git remote remove git remote set-head (-a | --auto | -d | --delete | ) @@ -73,6 +73,13 @@ multiple branches without grabbing all branches. With `-m ` option, a symbolic-ref `refs/remotes//HEAD` is set up to point at remote's __ branch. See also the set-head command. + +With `--set-head` option, a symbolic-ref `refs/remotes//HEAD` is set +up to point at the remote's default branch, mirroring the behavior of +`git clone`. This is equivalent to running `git remote set-head -a` +after the remote is added, and implies `-f` so that the remote's refs are +available locally. It cannot be combined with `-m ` or with a push +mirror. ++ When a fetch mirror is created with `--mirror=fetch`, the refs will not be stored in the `refs/remotes/` namespace, but rather everything in `refs/` on the remote will be directly mirrored into `refs/` in the diff --git a/builtin/remote.c b/builtin/remote.c index de989ea3ba..8273b425a5 100644 --- a/builtin/remote.c +++ b/builtin/remote.c @@ -23,7 +23,7 @@ static const char * const builtin_remote_usage[] = { "git remote [-v | --verbose]", - N_("git remote add [-t ] [-m ] [-f] [--tags | --no-tags] [--mirror=] "), + N_("git remote add [-t ] [-m ] [-f] [--set-head] [--tags | --no-tags] [--mirror=] "), N_("git remote rename [--[no-]progress] "), N_("git remote remove "), N_("git remote set-head (-a | --auto | -d | --delete | )"), @@ -174,10 +174,21 @@ static int check_remote_collision(struct remote *remote, void *data) return 0; } +static int set_head_auto_for_remote(const char *name) +{ + struct child_process cmd = CHILD_PROCESS_INIT; + + strvec_pushl(&cmd.args, "remote", "set-head", "--auto", name, NULL); + cmd.git_cmd = 1; + if (run_command(&cmd)) + return error(_("Could not set up HEAD for %s"), name); + return 0; +} + static int add(int argc, const char **argv, const char *prefix, struct repository *repo UNUSED) { - int fetch = 0, fetch_tags = TAGS_DEFAULT; + int fetch = 0, fetch_tags = TAGS_DEFAULT, set_head_auto = 0; unsigned mirror = MIRROR_NONE; struct string_list track = STRING_LIST_INIT_NODUP; const char *master = NULL; @@ -195,6 +206,8 @@ static int add(int argc, const char **argv, const char *prefix, OPT_STRING_LIST('t', "track", &track, N_("branch"), N_("branch(es) to track")), OPT_STRING('m', "master", &master, N_("branch"), N_("master branch")), + OPT_BOOL(0, "set-head", &set_head_auto, + N_("set refs/remotes//HEAD according to remote (implies --fetch)")), OPT_CALLBACK_F(0, "mirror", &mirror, "(push|fetch)", N_("set up remote as a mirror to push to or fetch from"), PARSE_OPT_OPTARG | PARSE_OPT_COMP_ARG, parse_mirror_opt), @@ -211,6 +224,12 @@ static int add(int argc, const char **argv, const char *prefix, die(_("specifying a master branch makes no sense with --mirror")); if (mirror && !(mirror & MIRROR_FETCH) && track.nr) die(_("specifying branches to track makes sense only with fetch mirrors")); + if (set_head_auto && master) + die(_("--set-head and --master are mutually exclusive")); + if (set_head_auto && mirror && !(mirror & MIRROR_FETCH)) + die(_("--set-head makes no sense with a push mirror")); + if (set_head_auto) + fetch = 1; name = argv[0]; url = argv[1]; @@ -269,6 +288,9 @@ static int add(int argc, const char **argv, const char *prefix, result = error(_("Could not setup master '%s'"), master); } + if (set_head_auto && set_head_auto_for_remote(name)) + result = 1; + out: strbuf_release(&buf); strbuf_release(&buf2); diff --git a/t/t5505-remote.sh b/t/t5505-remote.sh index e592c0bcde..043c86315f 100755 --- a/t/t5505-remote.sh +++ b/t/t5505-remote.sh @@ -81,6 +81,14 @@ test_expect_success 'add another remote' ' ) ' +test_expect_success 'add remote with --set-head implies --fetch and sets HEAD' ' + test_when_finished "git -C test remote remove third" && + git -C test remote add --set-head third ../two && + echo refs/remotes/third/main >expect && + git -C test symbolic-ref refs/remotes/third/HEAD >actual && + test_cmp expect actual +' + test_expect_success 'setup bare clone for server' ' git clone --bare "file://$(pwd)/one" srv.bare && git -C srv.bare config --local uploadpack.allowfilter 1 && base-commit: 94f057755b7941b321fd11fec1b2e3ca5313a4e0 -- gitgitgadget ``` ## Ben Knoble, 2026-04-25 17:20 Subject: Re: [PATCH] remote: add --set-head option to 'git remote add' Message-ID: <6F9060F0-20EB-4B60-8677-86DA2AB39B35@gmail.com> In-Reply-To: ``` > Le 25 avr. 2026 à 07:19, Harald Nordgren via GitGitGadget a écrit : > > From: Harald Nordgren > > Mirror the behavior 'git clone' applies to its first remote: after > fetching, set refs/remotes//HEAD to the remote's default branch. > > Equivalent to running: > > git remote add -f > git remote set-head -a > > The new option implies --fetch. > > Signed-off-by: Harald Nordgren > --- > remote: add --set-head option to 'git remote add' > > When using GitHub's gh tool to fork a repo, it seems that set-head isn't > run on the upstream remote. So its default branch is not recorded > locally, meaning that 'git log fork' will not work. > > With git remote add --set-head upstream , the default branch is set in > the same step and things can work out of the box after a small change on > 'gh' that I will do as a next step. I’m not totally opposed to this convenience, but couldn’t we also just teach gh to run set-head as a second command? (Of course, it will need a version check; if memory serves not all Git versions used in practice have this command? But I am on mobile and have not validated the history of git-remote’s sub-commands.) ``` ## Harald Nordgren, 2026-04-25 18:07 Subject: gh Message-ID: <20260425180749.49933-1-haraldnordgren@gmail.com> In-Reply-To: <6F9060F0-20EB-4B60-8677-86DA2AB39B35@gmail.com> ``` > I’m not totally opposed to this convenience, but couldn’t we also just teach gh to run set-head as a second command? We probably could, and maybe we should. One argument for this new options is that I believe 'git clone' has this behavior, so it's attractive if forking (adding a secondary remote) could work in the same way as clone (adding the first remote). Harald ``` ## Junio C Hamano, 2026-04-25 21:58 Subject: Re: [PATCH] remote: add --set-head option to 'git remote add' Message-ID: In-Reply-To: ``` "Harald Nordgren via GitGitGadget" writes: > From: Harald Nordgren > > Mirror the behavior 'git clone' applies to its first remote: after > fetching, set refs/remotes//HEAD to the remote's default branch. > > Equivalent to running: > > git remote add -f > git remote set-head -a > > The new option implies --fetch. Should this option (and the auto mode of "git remote set-head") even be necessary as an extra thing that the end-user should need to be aware of these days? It feels to me that the "fetch" part of "git remote add --fetch" command should behave in line with what "git fetch" from the remote does with "remote..followRemoteHEAD" configuration. Of course, the current implementation may not do so, and that is why you are sending this patch. A patch would need to plumb through the mechanism, but I think this should be pretty much automatic without giving more control than what the users already have. And because remote..followRemoteHEAD that is unconfigured is the same as setting it to "create", it means "git remote add -f" will behave just like "git clone" would to remember the upstream choice of which of their branches is the primary one (which is what HEAD in the publishing repository means), unless the variable is explicitly configured to "never". IOW, I think this should/can be done as a bugfix, i.e., Even though "git clone -o " does, "git remote add --fetch " does not create refs/remotes//HEAD. Fix it by making it honor the remote..followRemoteHEAD configuration variable, which was invented exactly for this purpose.. or something. ``` ## Jeff King, 2026-04-25 22:06 Subject: Re: [PATCH] remote: add --set-head option to 'git remote add' Message-ID: <20260425220629.GA28590@coredump.intra.peff.net> In-Reply-To: ``` On Sun, Apr 26, 2026 at 06:58:55AM +0900, Junio C Hamano wrote: > "Harald Nordgren via GitGitGadget" writes: > > > From: Harald Nordgren > > > > Mirror the behavior 'git clone' applies to its first remote: after > > fetching, set refs/remotes//HEAD to the remote's default branch. > > > > Equivalent to running: > > > > git remote add -f > > git remote set-head -a > > > > The new option implies --fetch. > > Should this option (and the auto mode of "git remote set-head") even > be necessary as an extra thing that the end-user should need to be > aware of these days? > > It feels to me that the "fetch" part of "git remote add --fetch" > command should behave in line with what "git fetch" from the remote > does with "remote..followRemoteHEAD" configuration. It already does, doesn't it? Doing: $ git init $ git remote add --fetch origin /path/to/some/repo $ git for-each-ref shows an origin/HEAD link. Which I think is not too surprising, as it is just calling "git fetch" under the hood. -Peff ``` ## Harald Nordgren, 2026-04-26 08:21 Subject: Re: [PATCH] remote: add --set-head option to 'git remote add' Message-ID: <20260426082106.11266-1-haraldnordgren@gmail.com> In-Reply-To: <20260425220629.GA28590@coredump.intra.peff.net> ``` > It already does, doesn't it? Doing: > > $ git init > $ git remote add --fetch origin /path/to/some/repo > $ git for-each-ref > > shows an origin/HEAD link. > > Which I think is not too surprising, as it is just calling "git fetch" > under the hood. I think you are right! So maybe all of this new code is not needed at all. Harald ```