Deprecate git_describe_command in favor of scm.git.describe_command

- implement backward compatibility handling
- Update documentation and tests to reflect changes

Author: RonnyPfannschmidt

docs/config.md

@@ -92,7 +92,7 @@ Callables or other Python objects have to be passed in `setup.py` (via the `use_
     this is a function for advanced use and you should be
     familiar with the `setuptools-scm` internals to use it.
 
-`git_describe_command`
+`scm.git.describe_command`
 :   This command will be used instead the default `git describe --long` command.
 
     Defaults to the value set by [setuptools_scm.git.DEFAULT_DESCRIBE][]
@@ -106,11 +106,16 @@ Callables or other Python objects have to be passed in `setup.py` (via the `use_
     - `"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
+        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.
 
+`git_describe_command` (deprecated)
+:   **Deprecated since 8.4.0**: Use `scm.git.describe_command` instead.
+
+    This field is maintained for backward compatibility but will issue a deprecation warning when used.
+
 `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

@@ -40,9 +40,10 @@ dynamic = ["version"]
 # 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)
+# Example: Git-specific configuration
 [tool.setuptools_scm.scm.git]
-pre_parse = "fail_on_missing_submodules"
+pre_parse = "fail_on_missing_submodules"  # Fail if submodules are not initialized
+describe_command = "git describe --dirty --tags --long --exclude *js*"  # Custom describe command
 ```
 
 Both approaches will work with projects that support PEP 518 ([pip](https://pypi.org/project/pip) and

src/setuptools_scm/_config.py

@@ -30,6 +30,57 @@
 
 log = _log.log.getChild("config")
 
+
+def _is_called_from_dataclasses() -> bool:
+    """Check if the current call is from the dataclasses module."""
+    import inspect
+
+    frame = inspect.currentframe()
+    try:
+        # Walk up to 7 frames to check for dataclasses calls
+        current_frame = frame
+        assert current_frame is not None
+        for _ in range(7):
+            current_frame = current_frame.f_back
+            if current_frame is None:
+                break
+            if "dataclasses.py" in current_frame.f_code.co_filename:
+                return True
+        return False
+    finally:
+        del frame
+
+
+class _GitDescribeCommandDescriptor:
+    """Data descriptor for deprecated git_describe_command field."""
+
+    def __get__(
+        self, obj: Configuration | None, objtype: type[Configuration] | None = None
+    ) -> _t.CMD_TYPE | None:
+        if obj is None:
+            return self  # type: ignore[return-value]
+
+        # Only warn if not being called by dataclasses.replace or similar introspection
+        is_from_dataclasses = _is_called_from_dataclasses()
+        if not is_from_dataclasses:
+            warnings.warn(
+                "Configuration field 'git_describe_command' is deprecated. "
+                "Use 'scm.git.describe_command' instead.",
+                DeprecationWarning,
+                stacklevel=2,
+            )
+        return obj.scm.git.describe_command
+
+    def __set__(self, obj: Configuration, value: _t.CMD_TYPE | None) -> None:
+        warnings.warn(
+            "Configuration field 'git_describe_command' is deprecated. "
+            "Use 'scm.git.describe_command' instead.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        obj.scm.git.describe_command = value
+
+
 DEFAULT_TAG_REGEX = re.compile(
     r"^(?:[\w-]+-)?(?P<version>[vV]?\d+(?:\.\d+){0,2}[^\+]*)(?:\+.*)?$"
 )
@@ -101,6 +152,7 @@ class GitConfiguration:
     pre_parse: git.GitPreParse = dataclasses.field(
         default_factory=lambda: _get_default_git_pre_parse()
     )
+    describe_command: _t.CMD_TYPE | None = None
 
     @classmethod
     def from_data(cls, data: dict[str, Any]) -> GitConfiguration:
@@ -158,7 +210,10 @@ class Configuration:
     version_file: _t.PathT | None = None
     version_file_template: str | None = None
     parse: ParseFunction | None = None
-    git_describe_command: _t.CMD_TYPE | None = None
+    git_describe_command: dataclasses.InitVar[_t.CMD_TYPE | None] = (
+        _GitDescribeCommandDescriptor()
+    )
+
     dist_name: str | None = None
     version_cls: type[_VersionT] = _Version
     search_parent_directories: bool = False
@@ -170,9 +225,42 @@ class Configuration:
         default_factory=lambda: ScmConfiguration()
     )
 
-    def __post_init__(self) -> None:
+    # Deprecated fields (handled in __post_init__)
+
+    def __post_init__(self, git_describe_command: _t.CMD_TYPE | None) -> None:
         self.tag_regex = _check_tag_regex(self.tag_regex)
 
+        # Handle deprecated git_describe_command
+        # Check if it's a descriptor object (happens when no value is passed)
+        if git_describe_command is not None and not isinstance(
+            git_describe_command, _GitDescribeCommandDescriptor
+        ):
+            # Check if this is being called from dataclasses
+            is_from_dataclasses = _is_called_from_dataclasses()
+
+            same_value = (
+                self.scm.git.describe_command is not None
+                and self.scm.git.describe_command == git_describe_command
+            )
+
+            if is_from_dataclasses and same_value:
+                # Ignore the passed value - it's from dataclasses.replace() with same value
+                pass
+            else:
+                warnings.warn(
+                    "Configuration field 'git_describe_command' is deprecated. "
+                    "Use 'scm.git.describe_command' instead.",
+                    DeprecationWarning,
+                    stacklevel=2,
+                )
+                # Check for conflicts
+                if self.scm.git.describe_command is not None:
+                    raise ValueError(
+                        "Cannot specify both 'git_describe_command' (deprecated) and "
+                        "'scm.git.describe_command'. Please use only 'scm.git.describe_command'."
+                    )
+                self.scm.git.describe_command = git_describe_command
+
     @property
     def absolute_root(self) -> str:
         return _check_absolute_root(self.root, self.relative_to)
@@ -227,6 +315,9 @@ def from_data(
 
         # Handle nested SCM configuration
         scm_data = data.pop("scm", {})
+
+        # Handle nested SCM configuration
+
         scm_config = ScmConfiguration.from_data(scm_data)
 
         return cls(

src/setuptools_scm/_get_version_impl.py

@@ -154,6 +154,7 @@ def get_version(
     version_cls: Any | None = None,
     normalize: bool = True,
     search_parent_directories: bool = False,
+    scm: dict[str, Any] | None = None,
 ) -> str:
     """
     If supplied, relative_to should be a file from which root may
@@ -165,7 +166,19 @@ def get_version(
     version_cls = _validate_version_cls(version_cls, normalize)
     del normalize
     tag_regex = parse_tag_regex(tag_regex)
-    config = Configuration(**locals())
+
+    # Handle scm parameter by converting it to ScmConfiguration
+    if scm is not None:
+        scm_config = _config.ScmConfiguration.from_data(scm)
+    else:
+        scm_config = _config.ScmConfiguration()
+
+    # Remove scm from locals() since we handle it separately
+    config_params = locals().copy()
+    config_params.pop("scm", None)
+    config_params.pop("scm_config", None)
+
+    config = _config.Configuration(scm=scm_config, **config_params)
     maybe_version = _get_version(config, force_write_version_files=True)
 
     if maybe_version is None:

src/setuptools_scm/git.py

@@ -330,8 +330,8 @@ def version_from_describe(
     config: Configuration,
     describe_command: _t.CMD_TYPE | None,
 ) -> ScmVersion | None:
-    if config.git_describe_command is not None:
-        describe_command = config.git_describe_command
+    if config.scm.git.describe_command is not None:
+        describe_command = config.scm.git.describe_command
 
     if describe_command is not None:
         if isinstance(describe_command, str):

testing/test_git.py

@@ -435,7 +435,11 @@ def test_not_matching_tags(wd: WorkDir) -> None:
     wd.commit_testfile()
     assert wd.get_version(
         tag_regex=r"^apache-arrow-([\.0-9]+)$",
-        git_describe_command="git describe --dirty --tags --long --exclude *js* ",
+        scm={
+            "git": {
+                "describe_command": "git describe --dirty --tags --long --exclude *js* "
+            }
+        },
     ).startswith("0.11.2")
 
 
@@ -758,3 +762,64 @@ def test_invalid_git_pre_parse_raises_error() -> None:
         ValueError, match="Invalid git pre_parse function 'invalid_function'"
     ):
         Configuration.from_data(relative_to=".", data=invalid_config_data)
+
+
+def test_git_describe_command_backward_compatibility() -> None:
+    """Test backward compatibility for git_describe_command configuration."""
+    # Test old configuration style still works with deprecation warning
+    old_config_data = {
+        "git_describe_command": "git describe --dirty --tags --long --exclude *js*"
+    }
+
+    with pytest.warns(DeprecationWarning, match=r"git_describe_command.*deprecated"):
+        config = Configuration.from_data(relative_to=".", data=old_config_data)
+
+    # Verify it was migrated to the new location
+    assert (
+        config.scm.git.describe_command
+        == "git describe --dirty --tags --long --exclude *js*"
+    )
+
+
+def test_git_describe_command_from_data_conflict() -> None:
+    """Test that specifying both old and new configuration in from_data raises ValueError."""
+    # Both old and new configuration specified - should raise ValueError
+    mixed_config_data = {
+        "git_describe_command": "old command",
+        "scm": {"git": {"describe_command": "new command"}},
+    }
+
+    # The Configuration constructor should handle the conflict detection
+    with pytest.warns(DeprecationWarning, match=r"git_describe_command.*deprecated"):
+        with pytest.raises(
+            ValueError, match=r"Cannot specify both.*git_describe_command"
+        ):
+            Configuration.from_data(relative_to=".", data=mixed_config_data)
+
+
+def test_git_describe_command_init_argument_deprecation() -> None:
+    """Test that passing git_describe_command as init argument issues deprecation warning."""
+    # Test init argument
+    with pytest.warns(DeprecationWarning, match=r"git_describe_command.*deprecated"):
+        config = Configuration(git_describe_command="test command")
+
+    # Verify the value was migrated to the new location
+    assert config.scm.git.describe_command == "test command"
+
+
+def test_git_describe_command_init_conflict() -> None:
+    """Test that specifying both old and new configuration raises ValueError."""
+    from setuptools_scm._config import GitConfiguration
+    from setuptools_scm._config import ScmConfiguration
+
+    # Both old init arg and new configuration specified - should raise ValueError
+    with pytest.warns(DeprecationWarning, match=r"git_describe_command.*deprecated"):
+        with pytest.raises(
+            ValueError, match=r"Cannot specify both.*git_describe_command"
+        ):
+            Configuration(
+                git_describe_command="old command",
+                scm=ScmConfiguration(
+                    git=GitConfiguration(describe_command="new command")
+                ),
+            )