fix: prefer .git during repository discovery

<!-- agent -->
GitPython considered worktree administration and bare-repository signatures
before a worktree's real .git entry. Align discovery with Git so .git files
and directories win, malformed .git files stop discovery, and candidate git
directories validate HEAD plus commondir-backed object and ref storage. This
addresses GHSA-239g-whfq-7xj9.

Regression coverage compares ambiguous layouts with git rev-parse and rejects
invalid HEAD/.git metadata.

Git baseline: 15c6308cf7ad276b306aa5b3ababfbdebfb1a917; setup.c
setup_git_directory_gently_1(), is_git_directory(), and validate_headref().

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

Author: Byron

doc/source/changes.rst

@@ -9,6 +9,7 @@ Security fixes for
 
 * https://github.com/gitpython-developers/GitPython/security/advisories/GHSA-g5vv-9gxw-82hx
 * https://github.com/gitpython-developers/GitPython/security/advisories/GHSA-whh4-5q6c-9v3x
+* https://github.com/gitpython-developers/GitPython/security/advisories/GHSA-239g-whfq-7xj9
 
 If you can, also try and provide feedback on the upcoming v4 branch
 https://github.com/gitpython-developers/GitPython/pull/2177 - patches welcome.

git/repo/base.py

@@ -45,7 +45,6 @@
 
 from .fun import (
     find_submodule_git_dir,
-    find_worktree_git_dir,
     is_git_dir,
     rev_parse,
     touch,
@@ -290,37 +289,43 @@ def __init__(
                 raise NoSuchPathError(epath)
 
         # Walk up the path to find the `.git` dir.
-        curpath = epath
-        git_dir = None
+        curpath = os.fspath(epath) if epath is not None else ""
+        git_dir: Optional[str] = None
         while curpath:
             # ABOUT osp.NORMPATH
             # It's important to normalize the paths, as submodules will otherwise
             # initialize their repo instances with paths that depend on path-portions
             # that will not exist after being removed. It's just cleaner.
-            if (
-                osp.isfile(osp.join(curpath, "gitdir"))
-                and osp.isfile(osp.join(curpath, "commondir"))
-                and osp.isfile(osp.join(curpath, "HEAD"))
-            ):
-                git_dir = curpath
-
-                if "GIT_WORK_TREE" in os.environ:
-                    self._working_tree_dir = os.getenv("GIT_WORK_TREE")
-                else:
-                    # Linked worktree administrative directories store the path to the
-                    # worktree's .git file in their gitdir file (without "gitdir: " prefix).
-                    with open(osp.join(git_dir, "gitdir")) as fp:
-                        worktree_gitfile = fp.read().strip()
-
-                    if not osp.isabs(worktree_gitfile):
-                        worktree_gitfile = osp.normpath(osp.join(git_dir, worktree_gitfile))
-
-                    self._working_tree_dir = osp.dirname(worktree_gitfile)
+            dotgit = osp.join(curpath, ".git")
+            sm_gitpath = find_submodule_git_dir(dotgit)
+            if sm_gitpath is not None:
+                # Worktrees can use relative paths as of Git 2.48, so join to curpath.
+                git_dir = osp.normpath(osp.join(curpath, os.fspath(sm_gitpath)))
+                self._working_tree_dir = curpath
+                break
 
+            # Like Git, do not fall back to a bare repository or parent directory when
+            # a non-directory .git entry exists but is not a valid gitfile.
+            if osp.exists(dotgit) and not osp.isdir(dotgit):
                 break
 
             if is_git_dir(curpath):
                 git_dir = curpath
+                if osp.isfile(osp.join(curpath, "gitdir")) and osp.isfile(osp.join(curpath, "commondir")):
+                    if "GIT_WORK_TREE" in os.environ:
+                        self._working_tree_dir = os.getenv("GIT_WORK_TREE")
+                    else:
+                        # Linked worktree administrative directories store the path to
+                        # the worktree's .git file in gitdir (without a "gitdir: " prefix).
+                        with open(osp.join(git_dir, "gitdir")) as fp:
+                            worktree_gitfile = fp.read().strip()
+
+                        if not osp.isabs(worktree_gitfile):
+                            worktree_gitfile = osp.normpath(osp.join(git_dir, worktree_gitfile))
+
+                        self._working_tree_dir = osp.dirname(worktree_gitfile)
+                    break
+
                 # from man git-config : core.worktree
                 # Set the path to the root of the working tree. If GIT_COMMON_DIR
                 # environment variable is set, core.worktree is ignored and not used for
@@ -340,21 +345,6 @@ def __init__(
                     self._working_tree_dir = os.getenv("GIT_WORK_TREE")
                 break
 
-            dotgit = osp.join(curpath, ".git")
-            sm_gitpath = find_submodule_git_dir(dotgit)
-            if sm_gitpath is not None:
-                git_dir = osp.normpath(sm_gitpath)
-
-            sm_gitpath = find_submodule_git_dir(dotgit)
-            if sm_gitpath is None:
-                sm_gitpath = find_worktree_git_dir(dotgit)
-
-            if sm_gitpath is not None:
-                # worktrees can use relative paths as of Git 2.48, so we join to curpath
-                git_dir = osp.normpath(osp.join(curpath, sm_gitpath))
-                self._working_tree_dir = curpath
-                break
-
             if not search_parent_directories:
                 break
             curpath, tail = osp.split(curpath)

git/repo/fun.py

@@ -66,12 +66,38 @@ def is_git_dir(d: PathLike) -> bool:
         throw if we see directories which just look like a worktree dir, but are none.
     """
     if osp.isdir(d):
-        if (osp.isdir(osp.join(d, "objects")) or "GIT_OBJECT_DIRECTORY" in os.environ) and osp.isdir(
-            osp.join(d, "refs")
-        ):
-            headref = osp.join(d, "HEAD")
-            return osp.isfile(headref) or (osp.islink(headref) and os.readlink(headref).startswith("refs"))
-        elif (
+        headref = osp.join(d, "HEAD")
+        if osp.islink(headref):
+            try:
+                valid_head = os.readlink(headref).startswith("refs/")
+            except OSError:
+                valid_head = False
+        else:
+            try:
+                with open(headref, "rb") as fp:
+                    head = fp.read(256)
+            except OSError:
+                valid_head = False
+            else:
+                valid_head = (head.startswith(b"ref:") and head[4:].lstrip().startswith(b"refs/")) or bool(
+                    re.match(rb"(?:[0-9A-Fa-f]{64}|[0-9A-Fa-f]{40})", head)
+                )
+
+        common_dir = os.getenv("GIT_COMMON_DIR")
+        if common_dir is None:
+            try:
+                common_dir = (Path(d) / "commondir").read_text().rstrip("\r\n")
+            except FileNotFoundError:
+                common_dir = os.fspath(d)
+            except OSError:
+                common_dir = ""
+            else:
+                common_dir = osp.realpath(osp.join(d, common_dir)) if common_dir else ""
+
+        object_dir = os.getenv("GIT_OBJECT_DIRECTORY") or osp.join(common_dir, "objects")
+        if valid_head and osp.isdir(object_dir) and osp.isdir(osp.join(common_dir, "refs")):
+            return True
+        if (
             osp.isfile(osp.join(d, "gitdir"))
             and osp.isfile(osp.join(d, "commondir"))
             and osp.isfile(osp.join(d, "gitfile"))

test/test_repo.py

@@ -122,6 +122,46 @@ def test_new_should_raise_on_non_existent_path(self):
             nonexistent = osp.join(tdir, "foobar")
             self.assertRaises(NoSuchPathError, Repo, nonexistent)
 
+    def test_repo_discovery_prefers_dotgit(self):
+        layouts = {
+            "linked-worktree": {
+                "gitdir": ".git\n",
+                "commondir": ".git\n",
+                "HEAD": "ref: refs/heads/main\n",
+            },
+            "bare": {"objects": None, "refs": None, "HEAD": "ref: refs/heads/main\n"},
+        }
+
+        with tempfile.TemporaryDirectory() as tdir:
+            for name, entries in layouts.items():
+                path = Path(tdir) / name
+                Repo.init(path).close()
+                for entry, contents in entries.items():
+                    item = path / entry
+                    if contents is None:
+                        item.mkdir()
+                    else:
+                        item.write_text(contents)
+
+                with self.subTest(layout=name):
+                    expected_git_dir = Git(path).rev_parse("--absolute-git-dir")
+                    assert osp.samefile(Repo(path).git_dir, expected_git_dir)
+
+    def test_repo_discovery_rejects_invalid_metadata(self):
+        with tempfile.TemporaryDirectory() as tdir:
+            path = Path(tdir)
+            (path / "objects").mkdir()
+            (path / "refs").mkdir()
+            (path / "HEAD").write_text("not a ref")
+
+            with self.subTest(metadata="HEAD"):
+                self.assertRaises(InvalidGitRepositoryError, Repo, path)
+
+            (path / "HEAD").write_text("ref: refs/heads/main\n")
+            (path / ".git").write_text("not a gitfile")
+            with self.subTest(metadata=".git"):
+                self.assertRaises(InvalidGitRepositoryError, Repo, path)
+
     @with_rw_repo("0.3.2.1")
     def test_repo_creation_from_different_paths(self, rw_repo):
         r_from_gitdir = Repo(rw_repo.git_dir)