[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

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

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