introduce a mechanism to configure git pre-parse+submodule checks

fixes #846

Author: RonnyPfannschmidt

docs/config.md

@@ -97,6 +97,20 @@ Callables or other Python objects have to be passed in `setup.py` (via the `use_
 
     Defaults to the value set by [setuptools_scm.git.DEFAULT_DESCRIBE][]
 
+`scm.git.pre_parse`
+:   A string specifying which git pre-parse function to use before parsing version information.
+    Available options:
+
+    - `"warn_on_shallow"` (default): Warns when the repository is shallow
+    - `"fail_on_shallow"`: Fails with an error when the repository is shallow
+    - `"fetch_on_shallow"`: Automatically fetches to rectify shallow repositories
+    - `"fail_on_missing_submodules"`: Fails when submodules are defined but not initialized
+
+    The `"fail_on_missing_submodules"` option is useful to prevent packaging incomplete
+    projects when submodules are required for a complete build.
+
+    Note: This setting is overridden by any explicit `pre_parse` parameter passed to the git parse function.
+
 `normalize`
 :   A boolean flag indicating if the version string should be normalized.
     Defaults to `True`. Setting this to `False` is equivalent to setting

docs/usage.md

@@ -39,6 +39,10 @@ dynamic = ["version"]
 [tool.setuptools_scm]
 # Configure custom options here (version schemes, file writing, etc.)
 version_file = "src/mypackage/_version.py"
+
+# Example: Fail if submodules are not initialized (useful for projects requiring submodules)
+[tool.setuptools_scm.scm.git]
+pre_parse = "fail_on_missing_submodules"
 ```
 
 Both approaches will work with projects that support PEP 518 ([pip](https://pypi.org/project/pip) and

src/setuptools_scm/_config.py

@@ -8,10 +8,14 @@
 import warnings
 
 from pathlib import Path
+from typing import TYPE_CHECKING
 from typing import Any
 from typing import Pattern
 from typing import Protocol
 
+if TYPE_CHECKING:
+    from . import git
+
 from . import _log
 from . import _types as _t
 from ._integration.pyproject_reading import PyProjectData
@@ -52,6 +56,13 @@ def _check_tag_regex(value: str | Pattern[str] | None) -> Pattern[str]:
     return regex
 
 
+def _get_default_git_pre_parse() -> git.GitPreParse:
+    """Get the default git pre_parse enum value"""
+    from . import git
+
+    return git.GitPreParse.WARN_ON_SHALLOW
+
+
 class ParseFunction(Protocol):
     def __call__(
         self, root: _t.PathT, *, config: Configuration
@@ -83,6 +94,53 @@ def _check_absolute_root(root: _t.PathT, relative_to: _t.PathT | None) -> str:
     return os.path.abspath(root)
 
 
+@dataclasses.dataclass
+class GitConfiguration:
+    """Git-specific configuration options"""
+
+    pre_parse: git.GitPreParse = dataclasses.field(
+        default_factory=lambda: _get_default_git_pre_parse()
+    )
+
+    @classmethod
+    def from_data(cls, data: dict[str, Any]) -> GitConfiguration:
+        """Create GitConfiguration from configuration data, converting strings to enums"""
+        git_data = data.copy()
+
+        # Convert string pre_parse values to enum instances
+        if "pre_parse" in git_data and isinstance(git_data["pre_parse"], str):
+            from . import git
+
+            try:
+                git_data["pre_parse"] = git.GitPreParse(git_data["pre_parse"])
+            except ValueError as e:
+                valid_options = [option.value for option in git.GitPreParse]
+                raise ValueError(
+                    f"Invalid git pre_parse function '{git_data['pre_parse']}'. "
+                    f"Valid options are: {', '.join(valid_options)}"
+                ) from e
+
+        return cls(**git_data)
+
+
+@dataclasses.dataclass
+class ScmConfiguration:
+    """SCM-specific configuration options"""
+
+    git: GitConfiguration = dataclasses.field(default_factory=GitConfiguration)
+
+    @classmethod
+    def from_data(cls, data: dict[str, Any]) -> ScmConfiguration:
+        """Create ScmConfiguration from configuration data"""
+        scm_data = data.copy()
+
+        # Handle git-specific configuration
+        git_data = scm_data.pop("git", {})
+        git_config = GitConfiguration.from_data(git_data)
+
+        return cls(git=git_config, **scm_data)
+
+
 @dataclasses.dataclass
 class Configuration:
     """Global configuration model"""
@@ -107,6 +165,11 @@ class Configuration:
 
     parent: _t.PathT | None = None
 
+    # Nested SCM configurations
+    scm: ScmConfiguration = dataclasses.field(
+        default_factory=lambda: ScmConfiguration()
+    )
+
     def __post_init__(self) -> None:
         self.tag_regex = _check_tag_regex(self.tag_regex)
 
@@ -161,8 +224,14 @@ def from_data(
         version_cls = _validate_version_cls(
             data.pop("version_cls", None), data.pop("normalize", True)
         )
+
+        # Handle nested SCM configuration
+        scm_data = data.pop("scm", {})
+        scm_config = ScmConfiguration.from_data(scm_data)
+
         return cls(
             relative_to=relative_to,
             version_cls=version_cls,
+            scm=scm_config,
             **data,
         )

src/setuptools_scm/_types.py

@@ -26,3 +26,6 @@
 VERSION_SCHEME: TypeAlias = Union[str, Callable[["version.ScmVersion"], str]]
 VERSION_SCHEMES: TypeAlias = Union[List[str], Tuple[str, ...], VERSION_SCHEME]
 SCMVERSION: TypeAlias = "version.ScmVersion"
+
+# Git pre-parse function types
+GIT_PRE_PARSE: TypeAlias = Union[str, None]

src/setuptools_scm/git.py

@@ -11,6 +11,7 @@
 from datetime import date
 from datetime import datetime
 from datetime import timezone
+from enum import Enum
 from os.path import samefile
 from pathlib import Path
 from typing import TYPE_CHECKING
@@ -52,6 +53,15 @@
 ]
 
 
+class GitPreParse(Enum):
+    """Available git pre-parse functions"""
+
+    WARN_ON_SHALLOW = "warn_on_shallow"
+    FAIL_ON_SHALLOW = "fail_on_shallow"
+    FETCH_ON_SHALLOW = "fetch_on_shallow"
+    FAIL_ON_MISSING_SUBMODULES = "fail_on_missing_submodules"
+
+
 def run_git(
     args: Sequence[str | os.PathLike[str]],
     repo: Path,
@@ -209,6 +219,65 @@ def fail_on_shallow(wd: GitWorkdir) -> None:
         )
 
 
+def fail_on_missing_submodules(wd: GitWorkdir) -> None:
+    """
+    Fail if submodules are defined but not initialized/cloned.
+
+    This pre_parse function checks if there are submodules defined in .gitmodules
+    but not properly initialized (cloned). This helps prevent packaging incomplete
+    projects when submodules are required for a complete build.
+    """
+    gitmodules_path = wd.path / ".gitmodules"
+    if not gitmodules_path.exists():
+        # No submodules defined, nothing to check
+        return
+
+    # Get submodule status - lines starting with '-' indicate uninitialized submodules
+    status_result = run_git(["submodule", "status"], wd.path)
+    if status_result.returncode != 0:
+        # Command failed, might not be in a git repo or other error
+        log.debug("Failed to check submodule status: %s", status_result.stderr)
+        return
+
+    status_lines = (
+        status_result.stdout.strip().split("\n") if status_result.stdout.strip() else []
+    )
+    uninitialized_submodules = []
+
+    for line in status_lines:
+        line = line.strip()
+        if line.startswith("-"):
+            # Extract submodule path (everything after the commit hash)
+            parts = line.split()
+            if len(parts) >= 2:
+                submodule_path = parts[1]
+                uninitialized_submodules.append(submodule_path)
+
+    # If .gitmodules exists but git submodule status returns nothing,
+    # it means submodules are defined but not properly set up (common after cloning without --recurse-submodules)
+    if not status_lines and gitmodules_path.exists():
+        raise ValueError(
+            f"Submodules are defined in .gitmodules but not initialized in {wd.path}. "
+            f"Please run 'git submodule update --init --recursive' to initialize them."
+        )
+
+    if uninitialized_submodules:
+        submodule_list = ", ".join(uninitialized_submodules)
+        raise ValueError(
+            f"Submodules are not initialized in {wd.path}: {submodule_list}. "
+            f"Please run 'git submodule update --init --recursive' to initialize them."
+        )
+
+
+# Mapping from enum items to actual pre_parse functions
+_GIT_PRE_PARSE_FUNCTIONS: dict[GitPreParse, Callable[[GitWorkdir], None]] = {
+    GitPreParse.WARN_ON_SHALLOW: warn_on_shallow,
+    GitPreParse.FAIL_ON_SHALLOW: fail_on_shallow,
+    GitPreParse.FETCH_ON_SHALLOW: fetch_on_shallow,
+    GitPreParse.FAIL_ON_MISSING_SUBMODULES: fail_on_missing_submodules,
+}
+
+
 def get_working_directory(config: Configuration, root: _t.PathT) -> GitWorkdir | None:
     """
     Return the working directory (``GitWorkdir``).
@@ -231,16 +300,26 @@ def parse(
     root: _t.PathT,
     config: Configuration,
     describe_command: str | list[str] | None = None,
-    pre_parse: Callable[[GitWorkdir], None] = warn_on_shallow,
+    pre_parse: Callable[[GitWorkdir], None] | None = None,
 ) -> ScmVersion | None:
     """
-    :param pre_parse: experimental pre_parse action, may change at any time
+    :param pre_parse: experimental pre_parse action, may change at any time.
+                     Takes precedence over config.git_pre_parse if provided.
     """
     _require_command("git")
     wd = get_working_directory(config, root)
     if wd:
+        # Use function parameter first, then config setting, then default
+        if pre_parse is not None:
+            effective_pre_parse = pre_parse
+        else:
+            # config.scm.git.pre_parse is always a GitPreParse enum instance
+            effective_pre_parse = _GIT_PRE_PARSE_FUNCTIONS.get(
+                config.scm.git.pre_parse, warn_on_shallow
+            )
+
         return _git_parse_inner(
-            config, wd, describe_command=describe_command, pre_parse=pre_parse
+            config, wd, describe_command=describe_command, pre_parse=effective_pre_parse
         )
     else:
         return None