refactor: move overrides public API to vcs_versioning.overrides module

- Move GlobalOverrides class and all public accessor functions from _overrides.py to overrides.py
- Keep only internal implementation details (_read_pretended_version_for, _apply_metadata_overrides, etc.) in _overrides.py
- Add GlobalOverrides.from_active(**changes) method for creating modified copies
- Add GlobalOverrides.export(target) method for exporting to env or monkeypatch
- Make get_active_overrides() auto-create context from environment if none exists
- Remove redundant test_log_levels_when_unset test
- Update all internal imports to use public overrides module
- Add comprehensive tests for from_active() and export() methods
- Add integrator documentation at docs/integrators.md

This establishes a clean separation between public API (vcs_versioning.overrides)
and internal implementation (_overrides), making it easier for integrators to
discover and use the overrides system.

Author: RonnyPfannschmidt

docs/integrators.md

@@ -1,10 +1,16 @@
 # Overrides
 
+!!! info "For Integrators"
+
+    If you're building a tool that integrates vcs-versioning (like hatch-vcs), see the [Integrator Guide](integrators.md) for using the overrides API with custom prefixes and the `GlobalOverrides` context manager.
+
 ## About Overrides
 
 Environment variables provide runtime configuration overrides, primarily useful in CI/CD
 environments where you need different behavior without modifying `pyproject.toml` or code.
 
+All environment variables support both `SETUPTOOLS_SCM_*` and `VCS_VERSIONING_*` prefixes. The `VCS_VERSIONING_*` prefix serves as a universal fallback that works across all tools using vcs-versioning.
+
 ## Version Detection Overrides
 
 ### Pretend Versions
@@ -13,15 +19,15 @@ Override the version number at build time.
 
 **setuptools-scm usage:**
 
-The environment variable `SETUPTOOLS_SCM_PRETEND_VERSION` is used
+The environment variable `SETUPTOOLS_SCM_PRETEND_VERSION` (or `VCS_VERSIONING_PRETEND_VERSION`) is used
 as the override source for the version number unparsed string.
 
 !!! warning ""
 
     it is strongly recommended to use distribution-specific pretend versions
     (see below).
 
-`SETUPTOOLS_SCM_PRETEND_VERSION_FOR_${DIST_NAME}`
+`SETUPTOOLS_SCM_PRETEND_VERSION_FOR_${DIST_NAME}` or `VCS_VERSIONING_PRETEND_VERSION_FOR_${DIST_NAME}`
 :   Used as the primary source for the version number,
     in which case it will be an unparsed string.
     Specifying distribution-specific pretend versions will
@@ -31,7 +37,7 @@ as the override source for the version number unparsed string.
     The dist name normalization follows adapted PEP 503 semantics, with one or
     more of ".-\_" being replaced by a single "\_", and the name being upper-cased.
 
-    This will take precedence over ``SETUPTOOLS_SCM_PRETEND_VERSION``.
+    This will take precedence over the generic ``SETUPTOOLS_SCM_PRETEND_VERSION`` or ``VCS_VERSIONING_PRETEND_VERSION``.
 
 ### Pretend Metadata
 
@@ -112,8 +118,13 @@ Enable debug output from vcs-versioning.
 
 **setuptools-scm usage:**
 
-`SETUPTOOLS_SCM_DEBUG`
+`SETUPTOOLS_SCM_DEBUG` or `VCS_VERSIONING_DEBUG`
 :   Enable debug logging for version detection and processing.
+    Can be set to:
+    - `1` or any non-empty value to enable DEBUG level logging
+    - A level name: `DEBUG`, `INFO`, `WARNING`, `ERROR`, or `CRITICAL` (case-insensitive)
+    - A specific log level integer: `10` (DEBUG), `20` (INFO), `30` (WARNING), etc.
+    - `0` to disable debug logging
 
 ### Reproducible Builds
 

docs/overrides.md

@@ -8,6 +8,7 @@ nav:
   - integrations.md
   - extending.md
   - overrides.md
+  - integrators.md
   - changelog.md
 theme:
   name: material

mkdocs.yml

@@ -255,8 +255,9 @@ def test_hg_command_from_env(
     request: pytest.FixtureRequest,
     hg_exe: str,
 ) -> None:
-    with monkeypatch.context() as m:
-        m.setenv("SETUPTOOLS_SCM_HG_COMMAND", hg_exe)
-        m.setenv("PATH", str(hg_wd.cwd / "not-existing"))
-        # No module reloading needed - runtime configuration works immediately
+    from vcs_versioning.overrides import GlobalOverrides
+
+    monkeypatch.setenv("PATH", str(hg_wd.cwd / "not-existing"))
+    # Use from_active() to create modified overrides with custom hg command
+    with GlobalOverrides.from_active(hg_command=hg_exe):
         assert set(find_files()) == {"file"}

setuptools-scm/testing_scm/test_file_finder.py

@@ -6,7 +6,7 @@
 
 from vcs_versioning._overrides import _find_close_env_var_matches
 from vcs_versioning._overrides import _search_env_vars_with_prefix
-from vcs_versioning._overrides import read_named_env
+from vcs_versioning.overrides import read_named_env
 
 
 class TestSearchEnvVarsWithPrefix:

setuptools-scm/testing_scm/test_overrides.py

@@ -23,8 +23,10 @@
 
 
 def _get_hg_command() -> str:
-    """Get the hg command from environment, allowing runtime configuration."""
-    return os.environ.get("SETUPTOOLS_SCM_HG_COMMAND", "hg")
+    """Get the hg command from override context or environment."""
+    from ..overrides import get_hg_command
+
+    return get_hg_command()
 
 
 def run_hg(args: list[str], cwd: _t.PathT, **kwargs: Any) -> CompletedProcess:

vcs-versioning/src/vcs_versioning/_backends/_hg.py

@@ -17,42 +17,46 @@
 def main(
     args: list[str] | None = None, *, _given_pyproject_data: PyProjectData | None = None
 ) -> int:
-    # Configure logging at CLI entry point
-    _log.configure_logging()
+    from .overrides import GlobalOverrides
 
-    opts = _get_cli_opts(args)
-    inferred_root: str = opts.root or "."
+    # Apply global overrides for the entire CLI execution
+    with GlobalOverrides.from_env("SETUPTOOLS_SCM"):
+        # Configure logging at CLI entry point (uses overrides for debug level)
+        _log.configure_logging()
 
-    pyproject = opts.config or _find_pyproject(inferred_root)
+        opts = _get_cli_opts(args)
+        inferred_root: str = opts.root or "."
 
-    try:
-        config = Configuration.from_file(
-            pyproject,
-            root=(os.path.abspath(opts.root) if opts.root is not None else None),
-            pyproject_data=_given_pyproject_data,
-        )
-    except (LookupError, FileNotFoundError) as ex:
-        # no pyproject.toml OR no [tool.setuptools_scm]
-        print(
-            f"Warning: could not use {os.path.relpath(pyproject)},"
-            " using default configuration.\n"
-            f" Reason: {ex}.",
-            file=sys.stderr,
-        )
-        config = Configuration(root=inferred_root)
-    version: str | None
-    if opts.no_version:
-        version = "0.0.0+no-version-was-requested.fake-version"
-    else:
-        version = _get_version(
-            config, force_write_version_files=opts.force_write_version_files
-        )
-    if version is None:
-        raise SystemExit("ERROR: no version found for", opts)
-    if opts.strip_dev:
-        version = version.partition(".dev")[0]
+        pyproject = opts.config or _find_pyproject(inferred_root)
 
-    return command(opts, version, config)
+        try:
+            config = Configuration.from_file(
+                pyproject,
+                root=(os.path.abspath(opts.root) if opts.root is not None else None),
+                pyproject_data=_given_pyproject_data,
+            )
+        except (LookupError, FileNotFoundError) as ex:
+            # no pyproject.toml OR no [tool.setuptools_scm]
+            print(
+                f"Warning: could not use {os.path.relpath(pyproject)},"
+                " using default configuration.\n"
+                f" Reason: {ex}.",
+                file=sys.stderr,
+            )
+            config = Configuration(root=inferred_root)
+        version: str | None
+        if opts.no_version:
+            version = "0.0.0+no-version-was-requested.fake-version"
+        else:
+            version = _get_version(
+                config, force_write_version_files=opts.force_write_version_files
+            )
+        if version is None:
+            raise SystemExit("ERROR: no version found for", opts)
+        if opts.strip_dev:
+            version = version.partition(".dev")[0]
+
+        return command(opts, version, config)
 
 
 def _get_cli_opts(args: list[str] | None) -> argparse.Namespace:

vcs-versioning/src/vcs_versioning/_cli.py

@@ -6,8 +6,7 @@
 
 import contextlib
 import logging
-import os
-from collections.abc import Iterator, Mapping
+from collections.abc import Iterator
 
 # Logger names that need configuration
 LOGGER_NAMES = [
@@ -30,12 +29,18 @@ def make_default_handler() -> logging.Handler:
         return last_resort
 
 
-def _default_log_level(_env: Mapping[str, str] = os.environ) -> int:
-    # Check both env vars for backward compatibility
-    val: str | None = _env.get("VCS_VERSIONING_DEBUG") or _env.get(
-        "SETUPTOOLS_SCM_DEBUG"
-    )
-    return logging.WARNING if val is None else logging.DEBUG
+def _default_log_level() -> int:
+    """Get default log level from active GlobalOverrides context.
+
+    Returns:
+        logging level constant (DEBUG, WARNING, etc.)
+    """
+    # Import here to avoid circular imports
+    from .overrides import get_active_overrides
+
+    # Get log level from active override context
+    overrides = get_active_overrides()
+    return overrides.log_level()
 
 
 def _get_all_scm_loggers() -> list[logging.Logger]:
@@ -47,11 +52,12 @@ def _get_all_scm_loggers() -> list[logging.Logger]:
 _default_handler: logging.Handler | None = None
 
 
-def configure_logging(_env: Mapping[str, str] = os.environ) -> None:
+def configure_logging() -> None:
     """Configure logging for all SCM-related loggers.
 
     This should be called once at entry point (CLI, setuptools integration, etc.)
-    before any actual logging occurs.
+    before any actual logging occurs. Uses the active GlobalOverrides context
+    to determine the log level.
     """
     global _configured, _default_handler
     if _configured:
@@ -60,7 +66,7 @@ def configure_logging(_env: Mapping[str, str] = os.environ) -> None:
     if _default_handler is None:
         _default_handler = make_default_handler()
 
-    level = _default_log_level(_env)
+    level = _default_log_level()
 
     for logger in _get_all_scm_loggers():
         if not logger.handlers:

vcs-versioning/src/vcs_versioning/_log.py

@@ -1,8 +1,13 @@
+"""Internal implementation details for the overrides module.
+
+This module contains private helpers and functions used internally
+by vcs_versioning. Public API is exposed via the overrides module.
+"""
+
 from __future__ import annotations
 
 import dataclasses
 import logging
-import os
 from collections.abc import Mapping
 from difflib import get_close_matches
 from typing import Any
@@ -74,86 +79,13 @@ def _find_close_env_var_matches(
             candidates.append(suffix)
 
     # Use difflib to find close matches
-    close_matches = get_close_matches(
+    close_matches_list = get_close_matches(
         expected_suffix, candidates, n=3, cutoff=threshold
     )
 
-    return [f"{prefix}{match}" for match in close_matches if match != expected_suffix]
-
-
-def read_named_env(
-    *,
-    tool: str = "SETUPTOOLS_SCM",
-    name: str,
-    dist_name: str | None,
-    env: Mapping[str, str] = os.environ,
-) -> str | None:
-    """Read a named environment variable, with fallback search for dist-specific variants.
-
-    This function first tries the standard normalized environment variable name.
-    If that's not found and a dist_name is provided, it searches for alternative
-    normalizations and warns about potential issues.
-
-    Args:
-        tool: The tool prefix (default: "SETUPTOOLS_SCM")
-        name: The environment variable name component
-        dist_name: The distribution name for dist-specific variables
-        env: Environment dictionary to search in (defaults to os.environ)
-
-    Returns:
-        The environment variable value if found, None otherwise
-    """
-
-    # First try the generic version
-    generic_val = env.get(f"{tool}_{name}")
-
-    if dist_name is not None:
-        # Normalize the dist name using packaging.utils.canonicalize_name
-        canonical_dist_name = canonicalize_name(dist_name)
-        env_var_dist_name = canonical_dist_name.replace("-", "_").upper()
-        expected_env_var = f"{tool}_{name}_FOR_{env_var_dist_name}"
-
-        # Try the standard normalized name first
-        val = env.get(expected_env_var)
-        if val is not None:
-            return val
-
-        # If not found, search for alternative normalizations
-        prefix = f"{tool}_{name}_FOR_"
-        alternative_matches = _search_env_vars_with_prefix(prefix, dist_name, env)
-
-        if alternative_matches:
-            # Found alternative matches - use the first one but warn
-            env_var, value = alternative_matches[0]
-            log.warning(
-                "Found environment variable '%s' for dist name '%s', "
-                "but expected '%s'. Consider using the standard normalized name.",
-                env_var,
-                dist_name,
-                expected_env_var,
-            )
-            if len(alternative_matches) > 1:
-                other_vars = [var for var, _ in alternative_matches[1:]]
-                log.warning(
-                    "Multiple alternative environment variables found: %s. Using '%s'.",
-                    other_vars,
-                    env_var,
-                )
-            return value
-
-        # No exact or alternative matches found - look for potential typos
-        close_matches = _find_close_env_var_matches(prefix, env_var_dist_name, env)
-        if close_matches:
-            log.warning(
-                "Environment variable '%s' not found for dist name '%s' "
-                "(canonicalized as '%s'). Did you mean one of these? %s",
-                expected_env_var,
-                dist_name,
-                canonical_dist_name,
-                close_matches,
-            )
-
-    return generic_val
+    return [
+        f"{prefix}{match}" for match in close_matches_list if match != expected_suffix
+    ]
 
 
 def _read_pretended_metadata_for(
@@ -167,6 +99,8 @@ def _read_pretended_metadata_for(
     Returns a dictionary with metadata field overrides like:
     {"node": "g1337beef", "distance": 4}
     """
+    from .overrides import read_named_env
+
     log.debug("dist name: %s", config.dist_name)
 
     pretended = read_named_env(name="PRETEND_METADATA", dist_name=config.dist_name)
@@ -281,6 +215,8 @@ def _read_pretended_version_for(
     tries ``SETUPTOOLS_SCM_PRETEND_VERSION``
     and ``SETUPTOOLS_SCM_PRETEND_VERSION_FOR_$UPPERCASE_DIST_NAME``
     """
+    from .overrides import read_named_env
+
     log.debug("dist name: %s", config.dist_name)
 
     pretended = read_named_env(name="PRETEND_VERSION", dist_name=config.dist_name)
@@ -292,5 +228,8 @@ def _read_pretended_version_for(
 
 
 def read_toml_overrides(dist_name: str | None) -> dict[str, Any]:
+    """Read TOML overrides from environment."""
+    from .overrides import read_named_env
+
     data = read_named_env(name="OVERRIDES", dist_name=dist_name)
     return load_toml_or_inline_map(data)