[PATCH] remote: add --set-head option to 'git remote add'

[PATCH] remote: add --set-head option to 'git remote add'

[Harald Nordgren via GitGitGadget]

From: Harald Nordgren <haraldnordgren@gmail.com>

Mirror the behavior 'git clone' applies to its first remote: after
fetching, set refs/remotes/<name>/HEAD to the remote's default branch.

Equivalent to running:

    git remote add -f <name> <url>
    git remote set-head <name> -a

The new option implies --fetch.

Signed-off-by: Harald Nordgren <haraldnordgren@gmail.com>
---
    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 <branch>] [-m <master>] [-f] [--[no-]tags] [--mirror=(fetch|push)] <name> <URL>
+git remote add [-t <branch>] [-m <master>] [-f] [--set-head] [--[no-]tags] [--mirror=(fetch|push)] <name> <URL>
 git remote rename [--[no-]progress] <old> <new>
 git remote remove <name>
 git remote set-head <name> (-a | --auto | -d | --delete | <branch>)
@@ -73,6 +73,13 @@ multiple branches without grabbing all branches.
 With `-m <master>` option, a symbolic-ref `refs/remotes/<name>/HEAD` is set
 up to point at remote's _<master>_ branch. See also the set-head command.
 +
+With `--set-head` option, a symbolic-ref `refs/remotes/<name>/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 <name> -a`
+after the remote is added, and implies `-f` so that the remote's refs are
+available locally. It cannot be combined with `-m <master>` 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 <branch>] [-m <master>] [-f] [--tags | --no-tags] [--mirror=<fetch|push>] <name> <url>"),
+	N_("git remote add [-t <branch>] [-m <master>] [-f] [--set-head] [--tags | --no-tags] [--mirror=<fetch|push>] <name> <url>"),
 	N_("git remote rename [--[no-]progress] <old> <new>"),
 	N_("git remote remove <name>"),
 	N_("git remote set-head <name> (-a | --auto | -d | --delete | <branch>)"),
@@ -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/<name>/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

Re: [PATCH] remote: add --set-head option to 'git remote add'

[Ben Knoble]

> Le 25 avr. 2026 à 07:19, Harald Nordgren via GitGitGadget <gitgitgadget@gmail.com> a écrit :
> 
> From: Harald Nordgren <haraldnordgren@gmail.com>
> 
> Mirror the behavior 'git clone' applies to its first remote: after
> fetching, set refs/remotes/<name>/HEAD to the remote's default branch.
> 
> Equivalent to running:
> 
>    git remote add -f <name> <url>
>    git remote set-head <name> -a
> 
> The new option implies --fetch.
> 
> Signed-off-by: Harald Nordgren <haraldnordgren@gmail.com>
> ---
>    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.)

gh

[Harald Nordgren]

> 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

Re: [PATCH] remote: add --set-head option to 'git remote add'

[Junio C Hamano]

"Harald Nordgren via GitGitGadget" <gitgitgadget@gmail.com> writes:

> From: Harald Nordgren <haraldnordgren@gmail.com>
>
> Mirror the behavior 'git clone' applies to its first remote: after
> fetching, set refs/remotes/<name>/HEAD to the remote's default branch.
>
> Equivalent to running:
>
>     git remote add -f <name> <url>
>     git remote set-head <name> -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.<name>.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.<name>.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 <name> <URL>" does, "git remote add
    --fetch <name> <URL>" does not create refs/remotes/<name>/HEAD.

    Fix it by making it honor the remote.<name>.followRemoteHEAD
    configuration variable, which was invented exactly for this
    purpose..

or something.

Re: [PATCH] remote: add --set-head option to 'git remote add'

[Jeff King]

On Sun, Apr 26, 2026 at 06:58:55AM +0900, Junio C Hamano wrote:

> "Harald Nordgren via GitGitGadget" <gitgitgadget@gmail.com> writes:
> 
> > From: Harald Nordgren <haraldnordgren@gmail.com>
> >
> > Mirror the behavior 'git clone' applies to its first remote: after
> > fetching, set refs/remotes/<name>/HEAD to the remote's default branch.
> >
> > Equivalent to running:
> >
> >     git remote add -f <name> <url>
> >     git remote set-head <name> -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.<name>.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

Re: [PATCH] remote: add --set-head option to 'git remote add'

[Harald Nordgren]

> 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

Re: Multiple remotes

[Ben Knoble]

> Le 25 avr. 2026 à 13:58, Harald Nordgren <haraldnordgren@gmail.com> a écrit :
> 
> 
>> 
>> The last one was a rhetorical question.  I do not want to see such a
>> configuration variable to implicitly trigger fetching at all.
> 
> 🤣
> 
> Good to clarify that when working with me so that I don't go ahead and
> implement that!
> 
>> If you are merely starting at a single arbitrary
>> commit, instead of anticipating to having to repeatedly sync with
>> the remote-tracking branch that will subsequently move, there is no
>> point jumping to a "freshest" commit that you haven't even seen let
>> alone inspected (i.e., you do not even know if it is a good base to
>> build on).
> 
> Not sure I understand this sentiment. For better or worse, the latest
> commit will decide what you have to work with -- unless we expect it to be
> reverted or forced pushed over.
> 
> What better starting point is there?
> 
>> For a starter, if you interact
>> with a repository with two or more branches, should
>> 
>>   $ git checkout --track=fetch -b topic origin/main
>> 
>> update an unrelated remote-tracking branch origin/maint from the
>> same remote?  As I already said, most Git tools _depend_ on the
>> stability of remote-tracking branches
> 
> This is an interesting question, and it's very likely that I am missing
> some nuance here. However, with that said what option does the developer
> have, you have to accept that the upstream changes constantly when others
> are working on it. What good does it do to keep the "head in the sand" any
> longer than necessary?
> 
> I'm not sure there is a way to fetch only 'origin/main' and avoid
> 'origin/maint'? Maybe, maybe, if that exists it could be useful here.

Isn’t that exactly what

    git fetch origin main

does? (Might need to expand the refspec.)

> 
>> still on a leave
> 
> Enjoy your vacation! I don't expect any response from you until you're back!
> 
> 
> Harald
> 

gh

[Harald Nordgren]

> Isn’t that exactly what
> 
>     git fetch origin main
> 
> does? (Might need to expand the refspec.)

Very good point, I will update it!


Harald