🔧 Explicit Git root configuration option

Author: patdhlk

docs/source/components/configuration.rst

@@ -361,6 +361,8 @@ Configures how **Sphinx-CodeLinks** analyse source files to extract markers from
    get_need_id_refs = true
    get_oneline_needs = true
    get_rst = true
+   # Optional: Explicit Git root for Bazel or deeply nested configs
+   # git_root = "/path/to/repo"
 
    [codelinks.projects.my_project.analyse.oneline_comment_style]
    start_sequence = "@"
@@ -420,6 +422,29 @@ Enables the extraction of marked RST text from source code comments. When enable
    [codelinks.projects.my_project.analyse]
    get_rst = false
 
+.. _`git_root`:
+
+git_root
+^^^^^^^^
+
+Specifies an explicit path to the Git repository root directory. This option is particularly useful in environments where the standard Git root auto-detection fails, such as:
+
+- **Bazel builds**: Where the execution path differs from the standard repository layout
+- **Deeply nested configurations**: Where ``conf.py`` is located in a deep subdirectory far from the repository root
+- **Custom build systems**: Where the working directory is different from the source repository
+
+When not set, **Sphinx-CodeLinks** will automatically traverse parent directories to locate the ``.git`` folder.
+
+**Type:** ``str`` (path)
+**Default:** Not set (auto-detection)
+
+.. code-block:: toml
+
+   [codelinks.projects.my_project.analyse]
+   git_root = "/absolute/path/to/repo"
+
+.. note:: When ``git_root`` is explicitly set, **Sphinx-CodeLinks** will use this path directly without attempting auto-detection. Ensure the path points to a valid Git repository containing a ``.git`` directory.
+
 .. _`oneline_comment_style`:
 
 analyse.oneline_comment_style

src/sphinx_codelinks/analyse/analyse.py

@@ -65,7 +65,11 @@ def __init__(
         self.oneline_needs: list[OneLineNeed] = []
         self.marked_rst: list[MarkedRst] = []
         self.all_marked_content: list[NeedIdRefs | OneLineNeed | MarkedRst] = []
-        self.git_root: Path | None = utils.locate_git_root(self.analyse_config.src_dir)
+        # Use explicitly configured git_root if provided, otherwise auto-detect
+        if self.analyse_config.git_root is not None:
+            self.git_root: Path | None = self.analyse_config.git_root.resolve()
+        else:
+            self.git_root = utils.locate_git_root(self.analyse_config.src_dir)
         self.git_remote_url: str | None = (
             utils.get_remote_url(self.git_root) if self.git_root else None
         )

src/sphinx_codelinks/config.py

@@ -305,6 +305,7 @@ class AnalyseSectionConfigType(TypedDict, total=False):
     get_oneline_needs: bool
     get_rst: bool
     outdir: str
+    git_root: str
     need_id_refs: NeedIdRefsConfigType
     marked_rst: MarkedRstConfigType
     oneline_comment_style: OneLineCommentStyleType
@@ -319,6 +320,7 @@ class SourceAnalyseConfigType(TypedDict, total=False):
     get_need_id_refs: bool
     get_oneline_needs: bool
     get_rst: bool
+    git_root: Path | None
     need_id_refs_config: NeedIdRefsConfig
     marked_rst_config: MarkedRstConfig
     oneline_comment_style: OneLineCommentStyle
@@ -361,6 +363,12 @@ def field_names(cls) -> set[str]:
     get_rst: bool = field(default=False, metadata={"schema": {"type": "boolean"}})
     """Whether to extract rst texts from comments"""
 
+    git_root: Path | None = field(
+        default=None, metadata={"schema": {"type": ["string", "null"]}}
+    )
+    """Explicit path to the Git repository root. If not set, it will be auto-detected
+    by traversing parent directories. Useful for Bazel builds or deeply nested configs."""
+
     need_id_refs_config: NeedIdRefsConfig = field(default_factory=NeedIdRefsConfig)
     """Configuration for extracting need id references from comments."""
 
@@ -765,9 +773,11 @@ def convert_analyse_config(
     if config_dict:
         for k, v in config_dict.items():
             if k not in {"online_comment_style", "need_id_refs", "marked_rst"}:
-                analyse_config_dict[k] = (  # type: ignore[literal-required]  # dynamical assignment
-                    Path(v) if k == "src_dic" and isinstance(v, str) else v
-                )
+                # Convert string paths to Path objects
+                if k in {"src_dir", "git_root"} and isinstance(v, str):
+                    analyse_config_dict[k] = Path(v)  # type: ignore[literal-required]
+                else:
+                    analyse_config_dict[k] = v  # type: ignore[literal-required]  # dynamical assignment
 
         # Get oneline_comment_style configuration
         oneline_comment_style_dict: OneLineCommentStyleType | None = config_dict.get(

tests/test_analyse.py

@@ -141,3 +141,72 @@ def test_analyse_oneline_needs(
     for src_file in src_analyse.src_files:
         cnt_comments += len(src_file.src_comments)
     assert cnt_comments == result["num_comments"]
+
+
+def test_explicit_git_root_configuration(tmp_path):
+    """Test that explicit git_root configuration is used instead of auto-detection."""
+    # Create a fake git repo structure in tmp_path
+    fake_git_root = tmp_path / "fake_repo"
+    fake_git_root.mkdir()
+    (fake_git_root / ".git").mkdir()
+
+    # Create a minimal .git/config with remote URL
+    git_config = fake_git_root / ".git" / "config"
+    git_config.write_text(
+        '[remote "origin"]\n    url = https://github.com/test/repo.git\n'
+    )
+
+    # Create HEAD file pointing to a branch ref
+    git_head = fake_git_root / ".git" / "HEAD"
+    git_head.write_text("ref: refs/heads/main\n")
+
+    # Create the refs/heads/main file with the commit hash
+    refs_dir = fake_git_root / ".git" / "refs" / "heads"
+    refs_dir.mkdir(parents=True)
+    (refs_dir / "main").write_text("abc123def456\n")
+
+    # Create source file in a deeply nested location
+    src_dir = tmp_path / "deeply" / "nested" / "src"
+    src_dir.mkdir(parents=True)
+    src_file = src_dir / "test.c"
+    src_file.write_text("// @Test, TEST_1\nvoid test() {}\n")
+
+    # Configure with explicit git_root
+    src_analyse_config = SourceAnalyseConfig(
+        src_files=[src_file],
+        src_dir=src_dir,
+        get_need_id_refs=False,
+        get_oneline_needs=True,
+        get_rst=False,
+        git_root=fake_git_root,
+    )
+
+    src_analyse = SourceAnalyse(src_analyse_config)
+
+    # Verify the explicit git_root was used
+    assert src_analyse.git_root == fake_git_root.resolve()
+    assert src_analyse.git_remote_url == "https://github.com/test/repo.git"
+    assert src_analyse.git_commit_rev == "abc123def456"
+
+
+def test_git_root_auto_detection_when_not_configured(tmp_path):
+    """Test that git_root is auto-detected when not explicitly configured."""
+    src_dir = TEST_DIR / "data" / "dcdc"
+    src_paths = [src_dir / "charge" / "demo_1.cpp"]
+
+    # Don't set git_root - it should auto-detect
+    src_analyse_config = SourceAnalyseConfig(
+        src_files=src_paths,
+        src_dir=src_dir,
+        get_need_id_refs=False,
+        get_oneline_needs=True,
+        get_rst=False,
+        # git_root is not set, so auto-detection should be used
+    )
+
+    src_analyse = SourceAnalyse(src_analyse_config)
+
+    # The test is running inside a git repo, so git_root should be detected
+    # We just verify it's not None (since this test runs in the sphinx-codelinks repo)
+    assert src_analyse.git_root is not None
+    assert (src_analyse.git_root / ".git").exists()