fix: Clone into dangling submodule metadata symlink targets on Windows

rubber stamp
<!-- agent -->
Removing a submodule retains its metadata alias but deletes the target.
Adding the same submodule again then passes a dangling directory symlink
to git clone --separate-git-dir. Git for Windows fails while copying its
template files through that alias. Both native-realpath and simulated
Windows 3.7 remove-leaf cases reproduced this failure locally.

When the metadata destination is a leaf symlink, pass its target to Git
and leave the alias intact. Resolve relative targets against the link's
parent, create missing target parents through the existing clone setup,
and let Git create the repository directory itself. Precreating that
directory is insufficient because Git rejects an existing separate git
repository destination.

Read the link explicitly because Python 3.7 on Windows cannot resolve a
dangling link with Path.resolve(). Normalize the Windows namespace prefix
returned by newer os.readlink implementations, including UNC targets,
and use forward slashes before passing the path through Git's URL logic.
The shared clone helper covers add() and initialization through update().

Add regression coverage for direct cloning through absolute and relative
dangling metadata links with missing target parents. Verify that the link
and its stored target are retained, metadata is created at the target,
and the resulting checkout works under both realpath modes.

Validation: 61 focused tests passed on Windows/Python 3.10 with
HIDE_WINDOWS_KNOWN_ERRORS=0, including both reported failures. Ruff 0.16.5
lint and formatting checks and git diff --check passed. Native Python 3.7
and UNC network shares were not available for execution. A broader run
also exposed sharing violations in sibling-reinitialization tests before
cloning; a representative case also failed with the unchanged HEAD clone
helper loaded in memory. That separate removal issue is not changed here.

Assisted-by: GPT 6.0
Co-authored-by: GPT 6.0 <codex@openai.com>

Author: Byron

git/objects/submodule/base.py

@@ -377,6 +377,18 @@ def _clone_repo(
                         repo.unsafe_git_clone_options,
                     )
             allow_unsafe_options = True
+            if osp.islink(module_abspath):
+                # Clone into the target while retaining the metadata alias. Git for
+                # Windows cannot initialize through a dangling directory symlink.
+                # Read the link explicitly for Python 3.7, and remove the Windows
+                # namespace prefix returned by newer Python versions for Git.
+                target = os.readlink(module_abspath)
+                if sys.platform == "win32":
+                    if target.startswith("\\\\?\\UNC\\"):
+                        target = "\\\\" + target[8:]
+                    elif target.startswith("\\\\?\\"):
+                        target = target[4:]
+                module_abspath = to_native_path_linux(osp.join(osp.dirname(module_abspath), target))
             kwargs["separate_git_dir"] = module_abspath
             module_abspath_dir = osp.dirname(module_abspath)
             if not osp.isdir(module_abspath_dir):

test/test_submodule.py

@@ -451,6 +451,25 @@ def test_remove_linked_metadata_keeps_siblings_and_can_reinitialize(
         assert Path(module.git.rev_parse("--show-toplevel")).resolve() == Path(sm.abspath).resolve()
 
 
+@pytest.mark.parametrize("relative_target", [False, True], ids=["absolute-target", "relative-target"])
+def test_add_to_dangling_metadata_symlink(movable_submodule, tmp_path, metadata_realpath, relative_target):
+    sm = movable_submodule
+    link = Path(sm.repo.git_dir) / "modules/new"
+    target = tmp_path / "missing" / "metadata"
+    link.symlink_to(osp.relpath(target, link.parent) if relative_target else target, target_is_directory=True)
+    link_target = os.readlink(link)
+
+    added = Submodule.add(sm.repo, "new", "new", sm.url)
+
+    assert link.is_symlink() and link.is_dir()
+    assert os.readlink(link) == link_target
+    assert (target / "HEAD").is_file()
+    with added.module() as module:
+        assert Path(module.git_dir).resolve() == target.resolve()
+        assert Path(module.git.rev_parse("--show-toplevel")).resolve() == Path(added.abspath).resolve()
+    assert Path(added.abspath, "file").read_text() == "content"
+
+
 class TestRootProgress(RootUpdateProgress):
     """Just prints messages, for now without checking the correctness of the states"""