Skip to content

submodule: support worktree-specific configuration - #2306

Open
yoichi wants to merge 3 commits into
gitgitgadget:masterfrom
yoichi:submodule-with-worktree
Open

yoichi wants to merge 3 commits into
gitgitgadget:masterfrom
yoichi:submodule-with-worktree

Conversation

@yoichi

@yoichi yoichi commented Nov 9, 2026 •

Copy link
Copy Markdown

When using multiple worktrees, submodule settings stored in the repository config are shared between all worktrees, even when they need to differ.

For example, different branches may use different URLs for the same submodule. More importantly, sharing submodule.<name>.gitdir causes submodule worktrees to share the same HEAD and index, even when the corresponding superproject worktrees record different commits for the submodule.

This series makes submodule settings worktree-specific when extensions.worktreeConfig is enabled. It also keeps submodule.<name>.gitdir relative for linked worktrees, so it continues to work when the worktree is moved along with the main worktree.

The changes include:

  • [1/3] Keep submodule.<name>.gitdir relative for linked worktrees.
  • [2/3] Store submodule settings in the worktree config when extensions.worktreeConfig is enabled.
  • [3/3] Make git submodule init copy an existing gitdir setting to the current worktree config only when it belongs to that worktree.

Changes in v2

  • Update the cover letter to better explain the problems this series addresses.
  • [1/3] Copy the string returned by worktree_git_path() early.
  • [2/3] Expand the explanation in the commit message for why the gitdir config is excluded from worktree add.
  • [3/3] Explain the case where the repository config contains a gitdir setting for another worktree, and warn when the setting is not copied.

cc: Yoichi NAKAYAMA yoichi.nakayama@gmail.com

@yoichi
yoichi force-pushed the submodule-with-worktree branch 6 times, most recently from 8e9091a to cdf089b Compare November 12, 2026 11:04
@yoichi

yoichi commented Nov 12, 2026

Copy link
Copy Markdown
Author

/submit

@gitgitgadget

gitgitgadget Bot commented Nov 12, 2026

Copy link
Copy Markdown

Submitted as pull.2306.git.1794484985.gitgitgadget@gmail.com

To fetch this version into FETCH_HEAD:

git fetch https://github.com/gitgitgadget/git/ pr-2306/yoichi/submodule-with-worktree-v1

To fetch this version to local tag pr-2306/yoichi/submodule-with-worktree-v1:

git fetch --no-tags https://github.com/gitgitgadget/git/ tag pr-2306/yoichi/submodule-with-worktree-v1

@@ -37,6 +37,7 @@
#include "wildmatch.h"

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yoichi NAKAYAMA wrote on the Git mailing list (how to reply to this email):

On Thu, Nov 12, 2026 at 9:03 PM Yoichi NAKAYAMA via GitGitGadget
<gitgitgadget@gmail.com> wrote:
>
> From: Yoichi NAKAYAMA <yoichi.nakayama@gmail.com>
>
> For a linked worktree, always keep `submodule.<name>.gitdir` relative
> to ensure it continues to work when the worktree is moved along with
> the main worktree. (This benefit also requires
> worktree.useRelativePaths to be set to true.)
>
> Signed-off-by: Yoichi NAKAYAMA <yoichi.nakayama@gmail.com>
> ---
>  builtin/submodule--helper.c                | 68 +++++++++++++---------
>  t/t7425-submodule-gitdir-path-extension.sh | 19 ++++++
>  2 files changed, 61 insertions(+), 26 deletions(-)
>
> diff --git a/builtin/submodule--helper.c b/builtin/submodule--helper.c
> index 461b682d0d..56d7720e93 100644
> --- a/builtin/submodule--helper.c
> +++ b/builtin/submodule--helper.c
> @@ -37,6 +37,7 @@
>  #include "wildmatch.h"
>  #include "strbuf.h"
>  #include "url.h"
> +#include "worktree.h"
>
>  #define OPT_QUIET (1 << 0)
>  #define OPT_CACHED (1 << 1)
> @@ -507,50 +508,60 @@ static int validate_and_set_submodule_gitdir(struct strbuf *gitdir_path,
>
>  static void create_default_gitdir_config(const char *submodule_name)
>  {
> +       struct worktree *wt = get_current_worktree(the_repository);
> +       const char *modules_dir;
> +       struct strbuf tmp = STRBUF_INIT;
>         struct strbuf gitdir_path = STRBUF_INIT;
>         struct git_hash_ctx ctx;
>         char hex_name_hash[GIT_MAX_HEXSZ + 1], header[128];
>         unsigned char raw_name_hash[GIT_MAX_RAWSZ];
>         int header_len;
>
> -       /* Case 1: try the plain module name */
> -       repo_git_path_append(the_repository, &gitdir_path, "modules/%s", submodule_name);
> -       if (!validate_and_set_submodule_gitdir(&gitdir_path, submodule_name)) {
> -               strbuf_release(&gitdir_path);
> -               return;
> +       modules_dir = worktree_git_path(wt, "modules/");
> +       if (is_absolute_path(modules_dir)) {
> +               modules_dir = relative_path(modules_dir, wt->path, &tmp);
>         }

I noticed that worktree_git_path() returns a pointer to a static buffer managed
by get_pathname(). I'll copy the result into tmp immediately, before calling
other functions that might overwrite the buffer:

    modules_dir = worktree_git_path(wt, "modules/");
    if (is_absolute_path(modules_dir))
        relative_path(modules_dir, wt->path, &tmp);
    else
        strbuf_addstr(&tmp, modules_dir);
    modules_dir = tmp.buf;

Thanks,
-- 
Yoichi NAKAYAMA

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yoichi NAKAYAMA wrote on the Git mailing list (how to reply to this email):

On Sun, Nov 15, 2026 at 12:27 AM Yoichi NAKAYAMA
<yoichi.nakayama@gmail.com> wrote:
>
> On Thu, Nov 12, 2026 at 9:03 PM Yoichi NAKAYAMA via GitGitGadget
> <gitgitgadget@gmail.com> wrote:
> >
> > From: Yoichi NAKAYAMA <yoichi.nakayama@gmail.com>
> >
> > For a linked worktree, always keep `submodule.<name>.gitdir` relative
> > to ensure it continues to work when the worktree is moved along with
> > the main worktree. (This benefit also requires
> > worktree.useRelativePaths to be set to true.)
> >
> > Signed-off-by: Yoichi NAKAYAMA <yoichi.nakayama@gmail.com>
> > ---
> >  builtin/submodule--helper.c                | 68 +++++++++++++---------
> >  t/t7425-submodule-gitdir-path-extension.sh | 19 ++++++
> >  2 files changed, 61 insertions(+), 26 deletions(-)
> >
> > diff --git a/builtin/submodule--helper.c b/builtin/submodule--helper.c
> > index 461b682d0d..56d7720e93 100644
> > --- a/builtin/submodule--helper.c
> > +++ b/builtin/submodule--helper.c
> > @@ -37,6 +37,7 @@
> >  #include "wildmatch.h"
> >  #include "strbuf.h"
> >  #include "url.h"
> > +#include "worktree.h"
> >
> >  #define OPT_QUIET (1 << 0)
> >  #define OPT_CACHED (1 << 1)
> > @@ -507,50 +508,60 @@ static int validate_and_set_submodule_gitdir(struct strbuf *gitdir_path,
> >
> >  static void create_default_gitdir_config(const char *submodule_name)
> >  {
> > +       struct worktree *wt = get_current_worktree(the_repository);
> > +       const char *modules_dir;
> > +       struct strbuf tmp = STRBUF_INIT;
> >         struct strbuf gitdir_path = STRBUF_INIT;
> >         struct git_hash_ctx ctx;
> >         char hex_name_hash[GIT_MAX_HEXSZ + 1], header[128];
> >         unsigned char raw_name_hash[GIT_MAX_RAWSZ];
> >         int header_len;
> >
> > -       /* Case 1: try the plain module name */
> > -       repo_git_path_append(the_repository, &gitdir_path, "modules/%s", submodule_name);
> > -       if (!validate_and_set_submodule_gitdir(&gitdir_path, submodule_name)) {
> > -               strbuf_release(&gitdir_path);
> > -               return;
> > +       modules_dir = worktree_git_path(wt, "modules/");
> > +       if (is_absolute_path(modules_dir)) {
> > +               modules_dir = relative_path(modules_dir, wt->path, &tmp);
> >         }
>
> I noticed that worktree_git_path() returns a pointer to a static buffer managed
> by get_pathname(). I'll copy the result into tmp immediately, before calling
> other functions that might overwrite the buffer:
>
>     modules_dir = worktree_git_path(wt, "modules/");
>     if (is_absolute_path(modules_dir))
>         relative_path(modules_dir, wt->path, &tmp);
>     else
>         strbuf_addstr(&tmp, modules_dir);
>     modules_dir = tmp.buf;

Correction: relative_path() does not always store the result in tmp.
The code should be:

    modules_dir = worktree_git_path(wt, "modules/");
    if (is_absolute_path(modules_dir)) {
        modules_dir = relative_path(modules_dir, wt->path, &tmp);
    } else {
        strbuf_addstr(&tmp, modules_dir);
        modules_dir = tmp.buf;
    }

Thanks,
-- 
Yoichi NAKAYAMA

@gitgitgadget

gitgitgadget Bot commented Nov 14, 2026

Copy link
Copy Markdown

User Yoichi NAKAYAMA <yoichi.nakayama@gmail.com> has been added to the cc: list.

For a linked worktree, always keep `submodule.<name>.gitdir` relative
to ensure it continues to work when the worktree is moved along with
the main worktree. (This benefit also requires
worktree.useRelativePaths to be set to true.)

Signed-off-by: Yoichi NAKAYAMA <yoichi.nakayama@gmail.com>
Submodule URLs can differ between branches. For example, one branch
may use the upstream repository while another uses a fork for the same
submodule. When these branches are checked out in separate worktrees,
storing `submodule.<name>.url` in the shared repository config
prevents each worktree from using its own URL.

Store submodule settings such as `submodule.<name>.active` and
`submodule.<name>.url` in the worktree config when
`extensions.worktreeConfig` is enabled.

Settings shared between worktrees can remain in the repository
config. When such a setting exists there, 'git submodule deinit' sets
`submodule.<name>.active` to false in the worktree config to
unregister the submodule.

Unlike other settings, `submodule.<name>.gitdir` must not be shared
between worktrees. Different commits in the superproject may record
different commits for the same submodule. If the gitdir is shared, the
submodule worktrees end up sharing the same `HEAD` and index, causing
Git commands to behave incorrectly. Therefore, store this setting in
the worktree config and exclude it from the config copied by 'git
worktree add'.

Signed-off-by: Yoichi NAKAYAMA <yoichi.nakayama@gmail.com>
@yoichi
yoichi force-pushed the submodule-with-worktree branch from cdf089b to a9eee2c Compare November 21, 2026 01:24
When extensions.worktreeConfig is enabled, an existing
`submodule.<name>.gitdir` setting in the repository config may have
been written by 'git submodule init' in another worktree. Reusing
that setting would cause the current worktree to use the submodule
gitdir of the other worktree.

Make 'git submodule init' copy an existing setting to the worktree
config only if it belongs to the current worktree; otherwise, generate
a new setting.

Warn when an existing setting does not match the current worktree and
is not copied to the worktree config.

Signed-off-by: Yoichi NAKAYAMA <yoichi.nakayama@gmail.com>
@yoichi
yoichi force-pushed the submodule-with-worktree branch from a9eee2c to b5d203d Compare November 21, 2026 06:47
@yoichi

yoichi commented Nov 21, 2026

Copy link
Copy Markdown
Author

/submit

@gitgitgadget

gitgitgadget Bot commented Nov 21, 2026

Copy link
Copy Markdown

Submitted as pull.2306.v2.git.1795273853.gitgitgadget@gmail.com

To fetch this version into FETCH_HEAD:

git fetch https://github.com/gitgitgadget/git/ pr-2306/yoichi/submodule-with-worktree-v2

To fetch this version to local tag pr-2306/yoichi/submodule-with-worktree-v2:

git fetch --no-tags https://github.com/gitgitgadget/git/ tag pr-2306/yoichi/submodule-with-worktree-v2

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant