fix: recognize git worktree root in find_vcs_root()

In a git worktree (or a submodule) the ".git" entry is a file
containing a "gitdir: <path>" pointer rather than a directory.
`_is_valid_vcs_dir()` only accepted directories, so `find_vcs_root()`
walked past the worktree root and failed to locate the project root,
breaking `molecule.yml` discovery for users working inside a worktree.

Treat a ".git" file as a valid VCS root marker when it contains a
"gitdir:" pointer, while still rejecting unrelated stray ".git" files.

Refs: #4142

Author: evadeflow

.config/dictionary.txt

@@ -22,6 +22,7 @@ Ulimits
 Unittests
 Virt
 Virt's
+Worktree
 XDIST
 antsibull
 anyconfig
@@ -63,6 +64,7 @@ followlinks
 fooo
 frob
 getfixturevalue
+gitdir
 goss
 hookwrapper
 hostvars
@@ -144,6 +146,7 @@ vfoo
 virtenv
 virtualmachines
 webservers
+worktree
 worktrees
 yourcollection
 yournamespace

src/molecule/util.py

@@ -525,23 +525,30 @@ def _filter_platforms(
 
 
 def _is_valid_vcs_dir(path: Path, name: str) -> bool:
-    """Check if a VCS directory is a genuine repository root.
+    """Check if a VCS entry marks a genuine repository root.
 
     Args:
         path: Parent directory to check.
-        name: VCS directory name (e.g. ".git", ".hg", ".svn").
+        name: VCS entry name (e.g. ".git", ".hg", ".svn").
 
     Returns:
-        Whether the VCS directory is a genuine repository root.
-    """
-    vcs_dir = path / name
-    if not vcs_dir.is_dir():
+        Whether the VCS entry marks a genuine repository root.
+    """
+    vcs_entry = path / name
+    # In a git worktree (or a submodule) the ".git" entry is a file
+    # containing a "gitdir: <path>" pointer rather than a directory.
+    if name == ".git" and vcs_entry.is_file():
+        try:
+            return vcs_entry.read_text(encoding="utf-8").startswith("gitdir:")
+        except OSError:
+            return False
+    if not vcs_entry.is_dir():
         return False
     # A real .git directory always contains a HEAD file.
-    # Bare repos, worktrees, and regular repos all have it.
+    # Bare repos and regular repos all have it.
     # Spurious .git dirs (e.g. created by GitKraken) do not.
     if name == ".git":
-        return (vcs_dir / "HEAD").exists()
+        return (vcs_entry / "HEAD").exists()
     return True
 
 

tests/unit/test_util.py

@@ -1131,6 +1131,97 @@ def test_find_vcs_root_skips_fake_git_dir(tmp_path: Path) -> None:
     assert result == str(repo)
 
 
+def test_find_vcs_root_in_git_worktree(tmp_path: Path) -> None:
+    """Ensure find_vcs_root recognizes a worktree where .git is a file.
+
+    In a git worktree the ".git" entry is a file containing a
+    "gitdir: <path>" pointer rather than a directory.
+
+    Args:
+        tmp_path: pytest fixture for temporary directory.
+    """
+    # Worktree root: .git is a file pointing at the main repo's gitdir.
+    worktree = tmp_path / "worktree"
+    worktree.mkdir()
+    git_file = worktree / ".git"
+    git_file.write_text(f"gitdir: {tmp_path / 'main' / '.git' / 'worktrees' / 'wt'}\n")
+
+    subdir = worktree / "infra"
+    subdir.mkdir()
+
+    util.find_vcs_root.cache_clear()
+    result = util.find_vcs_root(location=str(subdir))
+    assert result == str(worktree)
+
+
+def test_find_vcs_root_skips_bogus_git_file(tmp_path: Path) -> None:
+    """Ensure find_vcs_root ignores a .git file without a gitdir pointer.
+
+    Args:
+        tmp_path: pytest fixture for temporary directory.
+    """
+    # Real repo at top level.
+    repo = tmp_path / "repo"
+    repo.mkdir()
+    git_dir = repo / ".git"
+    git_dir.mkdir()
+    (git_dir / "HEAD").write_text("ref: refs/heads/main\n")
+
+    # Subdirectory with a spurious .git file that is not a worktree pointer.
+    subdir = repo / "infra"
+    subdir.mkdir()
+    (subdir / ".git").write_text("not a gitdir pointer\n")
+
+    util.find_vcs_root.cache_clear()
+    result = util.find_vcs_root(location=str(subdir))
+    assert result == str(repo)
+
+
+def test_find_vcs_root_skips_unreadable_git_file(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """Ensure find_vcs_root ignores a .git file that cannot be read.
+
+    If reading the ".git" file raises OSError (e.g. permission denied),
+    the entry should be skipped rather than crash.
+
+    Args:
+        tmp_path: pytest fixture for temporary directory.
+        monkeypatch: pytest fixture for patching attributes.
+    """
+    # Real repo at top level.
+    repo = tmp_path / "repo"
+    repo.mkdir()
+    git_dir = repo / ".git"
+    git_dir.mkdir()
+    (git_dir / "HEAD").write_text("ref: refs/heads/main\n")
+
+    # Subdirectory with a .git file that will fail to read.
+    subdir = repo / "infra"
+    subdir.mkdir()
+    unreadable = subdir / ".git"
+    unreadable.write_text("gitdir: /somewhere\n")
+
+    original_read_text = Path.read_text
+
+    def raise_for_target(
+        self: Path,
+        encoding: str | None = None,
+        errors: str | None = None,
+    ) -> str:
+        if self == unreadable:
+            msg = "simulated permission error"
+            raise PermissionError(msg)
+        return original_read_text(self, encoding=encoding, errors=errors)
+
+    monkeypatch.setattr(Path, "read_text", raise_for_target)
+
+    util.find_vcs_root.cache_clear()
+    result = util.find_vcs_root(location=str(subdir))
+    assert result == str(repo)
+
+
 @pytest.mark.parametrize(
     ("input_value", "expected"),
     (