Git(feat[version]): Add structured version info via build_options()

- Add GitVersionInfo dataclass to provide structured git version output
- Update version() method to return raw string output
- Add build_options() method that returns a GitVersionInfo instance
- Fix doctests in vendored version module
- Use internal vendor.version module instead of external packaging

Author: tony

src/libvcs/cmd/git.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import dataclasses
 import datetime
 import pathlib
 import shlex
@@ -10,10 +11,37 @@
 
 from libvcs._internal.run import ProgressCallbackProtocol, run
 from libvcs._internal.types import StrOrBytesPath, StrPath
+from libvcs._vendor.version import InvalidVersion, parse
 
 _CMD = t.Union[StrOrBytesPath, Sequence[StrOrBytesPath]]
 
 
+@dataclasses.dataclass
+class GitVersionInfo:
+    """Information about the git version."""
+
+    version: str
+    """Git version string (e.g. '2.43.0')"""
+
+    version_info: tuple[int, int, int] | None = None
+    """Tuple of (major, minor, micro) version numbers, or None if version invalid"""
+
+    cpu: str | None = None
+    """CPU architecture information"""
+
+    commit: str | None = None
+    """Commit associated with this build"""
+
+    sizeof_long: str | None = None
+    """Size of long in the compiled binary"""
+
+    sizeof_size_t: str | None = None
+    """Size of size_t in the compiled binary"""
+
+    shell_path: str | None = None
+    """Shell path configured in git"""
+
+
 class Git:
     """Run commands directly on a git repository."""
 
@@ -1751,7 +1779,17 @@ def version(
         check_returncode: bool | None = None,
         **kwargs: t.Any,
     ) -> str:
-        """Version. Wraps `git version <https://git-scm.com/docs/git-version>`_.
+        """Get git version. Wraps `git version <https://git-scm.com/docs/git-version>`_.
+
+        Parameters
+        ----------
+        build_options : bool, optional
+            Include build options in the output with ``--build-options``
+
+        Returns
+        -------
+        str
+            Raw version string output
 
         Examples
         --------
@@ -1773,6 +1811,78 @@ def version(
             check_returncode=check_returncode,
         )
 
+    def build_options(
+        self,
+        *,
+        check_returncode: bool | None = None,
+        **kwargs: t.Any,
+    ) -> GitVersionInfo:
+        """Get detailed Git version information as a structured dataclass.
+
+        Runs ``git --version --build-options`` and parses the output.
+
+        Returns
+        -------
+        GitVersionInfo
+            Dataclass containing structured information about the git version and build
+
+        Examples
+        --------
+        >>> git = Git(path=example_git_repo.path)
+        >>> version_info = git.build_options()
+        >>> isinstance(version_info, GitVersionInfo)
+        True
+        >>> isinstance(version_info.version, str)
+        True
+        """
+        output = self.version(build_options=True, check_returncode=check_returncode)
+
+        # Parse the output into a structured format
+        result = GitVersionInfo(version="")
+
+        # First line is always "git version X.Y.Z"
+        lines = output.strip().split("\n")
+        if lines and lines[0].startswith("git version "):
+            version_str = lines[0].replace("git version ", "").strip()
+            result.version = version_str
+
+            # Parse semantic version components
+            try:
+                parsed_version = parse(version_str)
+                result.version_info = (
+                    parsed_version.major,
+                    parsed_version.minor,
+                    parsed_version.micro,
+                )
+            except InvalidVersion:
+                # Fall back to string-only if can't be parsed
+                result.version_info = None
+
+            # Parse additional build info
+            for line in lines[1:]:
+                line = line.strip()
+                if not line:
+                    continue
+
+                if ":" in line:
+                    key, value = line.split(":", 1)
+                    key = key.strip()
+                    value = value.strip()
+
+                    if key == "cpu":
+                        result.cpu = value
+                    elif key == "sizeof-long":
+                        result.sizeof_long = value
+                    elif key == "sizeof-size_t":
+                        result.sizeof_size_t = value
+                    elif key == "shell-path":
+                        result.shell_path = value
+                # Special handling for the commit line which often has no colon
+                elif "commit" in line:
+                    result.commit = line
+
+        return result
+
     def rev_parse(
         self,
         *,

tests/cmd/test_git.py

@@ -19,3 +19,82 @@ def test_git_constructor(
     repo = git.Git(path=path_type(tmp_path))
 
     assert repo.path == tmp_path
+
+
+def test_version_basic(monkeypatch: pytest.MonkeyPatch, tmp_path: pathlib.Path) -> None:
+    """Test basic git version output."""
+    git_cmd = git.Git(path=tmp_path)
+
+    monkeypatch.setattr(git_cmd, "run", lambda *args, **kwargs: "git version 2.43.0")
+
+    result = git_cmd.version()
+    assert result == "git version 2.43.0"
+
+
+def test_version_with_build_options(
+    monkeypatch: pytest.MonkeyPatch,
+    tmp_path: pathlib.Path,
+) -> None:
+    """Test git version with build options."""
+    git_cmd = git.Git(path=tmp_path)
+
+    sample_output = """git version 2.43.0
+cpu: x86_64
+no commit associated with this build
+sizeof-long: 8
+sizeof-size_t: 8
+shell-path: /bin/sh"""
+
+    def mock_run(cmd_args: list[str], **kwargs: t.Any) -> str:
+        assert cmd_args == ["version", "--build-options"]
+        assert kwargs.get("check_returncode") is None
+        return sample_output
+
+    monkeypatch.setattr(git_cmd, "run", mock_run)
+
+    result = git_cmd.version(build_options=True)
+    assert result == sample_output
+
+
+def test_build_options(monkeypatch: pytest.MonkeyPatch, tmp_path: pathlib.Path) -> None:
+    """Test build_options() method."""
+    git_cmd = git.Git(path=tmp_path)
+
+    sample_output = """git version 2.43.0
+cpu: x86_64
+no commit associated with this build
+sizeof-long: 8
+sizeof-size_t: 8
+shell-path: /bin/sh"""
+
+    # We need to fix the parsing for "no commit associated with this build"
+    # in the build_options() method
+    monkeypatch.setattr(git_cmd, "version", lambda **kwargs: sample_output)
+
+    result = git_cmd.build_options()
+
+    assert isinstance(result, git.GitVersionInfo)
+    assert result.version == "2.43.0"
+    assert result.version_info == (2, 43, 0)
+    assert result.cpu == "x86_64"
+    assert result.commit == "no commit associated with this build"
+    assert result.sizeof_long == "8"
+    assert result.sizeof_size_t == "8"
+    assert result.shell_path == "/bin/sh"
+
+
+def test_build_options_invalid_version(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: pathlib.Path
+) -> None:
+    """Test build_options() with invalid version string."""
+    git_cmd = git.Git(path=tmp_path)
+
+    sample_output = "git version development"
+
+    monkeypatch.setattr(git_cmd, "version", lambda **kwargs: sample_output)
+
+    result = git_cmd.build_options()
+
+    assert isinstance(result, git.GitVersionInfo)
+    assert result.version == "development"
+    assert result.version_info is None