git init compatibility, Git.version()

.tool-versions

@@ -1,2 +1,2 @@
-uv 0.7.3
+uv 0.7.5
 python 3.13.3 3.12.10 3.11.12 3.10.17 3.9.22 3.8.20 3.7.17

CHANGES

@@ -15,6 +15,12 @@ $ pip install --user --upgrade --pre libvcs
 
 <!-- Maintainers, insert changes / features for the next release here -->
 
+- Add `GitVersionInfo` dataclass and `build_options()` method to `Git` class to
+  provide structured access to git version information, making version handling more homogeneous
+  and type-safe (#491). The `version()` method now returns a `Version` object instead of a string.
+  This allows for more reliable version parsing and comparison, while `GitSync.get_git_version()`
+  continues to return a string for backward compatibility.
+
 ### Development
 
 - Cursor rules for development loop and git commit messages (#488)

CLAUDE.md

@@ -0,0 +1,259 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## CRITICAL REQUIREMENTS
+
+### Test Success
+- ALL tests MUST pass for code to be considered complete and working
+- Never describe code as "working as expected" if there are ANY failing tests
+- Even if specific feature tests pass, failing tests elsewhere indicate broken functionality
+- Changes that break existing tests must be fixed before considering implementation complete
+- A successful implementation must pass linting, type checking, AND all existing tests
+
+## Project Overview
+
+libvcs is a lite, typed Python tool for:
+- Detecting and parsing URLs for Git, Mercurial, and Subversion repositories
+- Providing command abstractions for git, hg, and svn
+- Synchronizing repositories locally
+- Creating pytest fixtures for testing with temporary repositories
+
+The library powers [vcspull](https://www.github.com/vcs-python/vcspull/), a tool for managing and synchronizing multiple git, svn, and mercurial repositories.
+
+## Development Environment
+
+This project uses:
+- Python 3.9+
+- [uv](https://github.com/astral-sh/uv) for dependency management
+- [ruff](https://github.com/astral-sh/ruff) for linting and formatting
+- [mypy](https://github.com/python/mypy) for type checking
+- [pytest](https://docs.pytest.org/) for testing
+
+## Common Commands
+
+### Setting Up Environment
+
+```bash
+# Install dependencies
+uv pip install --editable .
+uv pip sync
+
+# Install with development dependencies
+uv pip install --editable . -G dev
+```
+
+### Running Tests
+
+```bash
+# Run all tests
+make test
+# or directly with pytest
+uv run pytest
+
+# Run a single test file
+uv run pytest tests/sync/test_git.py
+
+# Run a specific test
+uv run pytest tests/sync/test_git.py::test_remotes
+
+# Run tests with test watcher
+make start
+# or
+uv run ptw .
+```
+
+### Linting and Type Checking
+
+```bash
+# Run ruff for linting
+make ruff
+# or directly
+uv run ruff check .
+
+# Format code with ruff
+make ruff_format
+# or directly
+uv run ruff format .
+
+# Run ruff linting with auto-fixes
+uv run ruff check . --fix --show-fixes
+
+# Run mypy for type checking
+make mypy
+# or directly
+uv run mypy src tests
+
+# Watch mode for linting (using entr)
+make watch_ruff
+make watch_mypy
+```
+
+### Development Workflow
+
+Follow this workflow for code changes:
+
+1. **Format First**: `uv run ruff format .`
+2. **Run Tests**: `uv run pytest`
+3. **Run Linting**: `uv run ruff check . --fix --show-fixes`
+4. **Check Types**: `uv run mypy`
+5. **Verify Tests Again**: `uv run pytest`
+
+### Documentation
+
+```bash
+# Build documentation
+make build_docs
+
+# Start documentation server with auto-reload
+make start_docs
+
+# Update documentation CSS/JS
+make design_docs
+```
+
+## Code Architecture
+
+libvcs is organized into three main modules:
+
+1. **URL Detection and Parsing** (`libvcs.url`)
+   - Base URL classes in `url/base.py`
+   - VCS-specific implementations in `url/git.py`, `url/hg.py`, and `url/svn.py`
+   - URL registry in `url/registry.py`
+   - Constants in `url/constants.py`
+
+2. **Command Abstraction** (`libvcs.cmd`)
+   - Command classes for git, hg, and svn in `cmd/git.py`, `cmd/hg.py`, and `cmd/svn.py`
+   - Built on top of Python's subprocess module (via `_internal/subprocess.py`)
+
+3. **Repository Synchronization** (`libvcs.sync`)
+   - Base sync classes in `sync/base.py`
+   - VCS-specific sync implementations in `sync/git.py`, `sync/hg.py`, and `sync/svn.py`
+
+4. **Internal Utilities** (`libvcs._internal`)
+   - Subprocess wrappers in `_internal/subprocess.py`
+   - Data structures in `_internal/dataclasses.py` and `_internal/query_list.py`
+   - Runtime helpers in `_internal/run.py` and `_internal/shortcuts.py`
+
+5. **pytest Plugin** (`libvcs.pytest_plugin`)
+   - Provides fixtures for creating temporary repositories for testing
+
+## Testing Strategy
+
+libvcs uses pytest for testing with many custom fixtures. The pytest plugin (`pytest_plugin.py`) defines fixtures for creating temporary repositories for testing. These include:
+
+- `create_git_remote_repo`: Creates a git repository for testing
+- `create_hg_remote_repo`: Creates a Mercurial repository for testing
+- `create_svn_remote_repo`: Creates a Subversion repository for testing
+- `git_repo`, `svn_repo`, `hg_repo`: Pre-made repository instances
+- `set_home`, `gitconfig`, `hgconfig`, `git_commit_envvars`: Environment fixtures
+
+These fixtures handle setup and teardown automatically, creating isolated test environments.
+
+For running tests with actual VCS commands, tests will be skipped if the corresponding VCS binary is not installed.
+
+### Example Fixture Usage
+
+```python
+def test_repo_sync(git_repo):
+    # git_repo is already a GitSync instance with a clean repository
+    # Use it directly in your tests
+    assert git_repo.get_revision() == "initial"
+```
+
+### Parameterized Tests
+
+Use `typing.NamedTuple` for parameterized tests:
+
+```python
+class RepoFixture(t.NamedTuple):
+    test_id: str  # For test naming
+    repo_args: dict[str, t.Any]
+    expected_result: str
+
+@pytest.mark.parametrize(
+    list(RepoFixture._fields),
+    REPO_FIXTURES,
+    ids=[test.test_id for test in REPO_FIXTURES],
+)
+def test_sync(
+    # Parameters and fixtures...
+):
+    # Test implementation
+```
+
+## Coding Standards
+
+### Imports
+
+- Use namespace imports: `import enum` instead of `from enum import Enum`
+- For typing, use `import typing as t` and access via namespace: `t.NamedTuple`, etc.
+- Use `from __future__ import annotations` at the top of all Python files
+
+### Docstrings
+
+Follow NumPy docstring style for all functions and methods:
+
+```python
+"""Short description of the function or class.
+
+Detailed description using reStructuredText format.
+
+Parameters
+----------
+param1 : type
+    Description of param1
+param2 : type
+    Description of param2
+
+Returns
+-------
+type
+    Description of return value
+"""
+```
+
+### Git Commit Standards
+
+Format commit messages as:
+```
+Component/File(commit-type[Subcomponent/method]): Concise description
+
+why: Explanation of necessity or impact.
+what:
+- Specific technical changes made
+- Focused on a single topic
+
+refs: #issue-number, breaking changes, or relevant links
+```
+
+Common commit types:
+- **feat**: New features or enhancements
+- **fix**: Bug fixes
+- **refactor**: Code restructuring without functional change
+- **docs**: Documentation updates
+- **chore**: Maintenance (dependencies, tooling, config)
+- **test**: Test-related updates
+- **style**: Code style and formatting
+
+Example:
+```
+url/git(feat[GitURL]): Add support for custom SSH port syntax
+
+why: Enable parsing of Git URLs with custom SSH ports
+what:
+- Add port capture to SCP_REGEX pattern
+- Update GitURL.to_url() to include port if specified
+- Add tests for the new functionality
+
+refs: #123
+```
+
+## Debugging Tips
+
+When stuck in debugging loops:
+
+1. **Pause and acknowledge the loop**
+2. **Minimize to MVP**: Remove all debugging cruft and experimental code
+3. **Document the issue** comprehensively for a fresh approach
+4. **Format for portability** (using quadruple backticks)

MIGRATION

@@ -24,6 +24,25 @@ _Notes on the upcoming release will be added here_
 
 <!-- Maintainers, insert migration notes for the next release here -->
 
+#### Git version handling API changes (#491)
+
+- `Git.version()` now returns a `Version` object instead of a string
+
+  Before:
+  ```python
+  git = Git(path=path)
+  version_str = git.version()  # returns a string like "2.43.0"
+  ```
+
+  After:
+  ```python
+  git = Git(path=path)
+  version_obj = git.version()  # returns a Version object
+  version_str = ".".join([str(x) for x in (version_obj.major, version_obj.minor, version_obj.micro)])
+  ```
+
+- `GitSync.get_git_version()` continues to return a string for backward compatibility
+
 #### pytest fixtures: `git_local_clone` renamed to `example_git_repo` (#468)
 
 - pytest: `git_local_clone` renamed to `example_git_repo`

pyproject.toml

@@ -213,8 +213,18 @@ convention = "numpy"
 "*/__init__.py" = ["F401"]
 
 [tool.pytest.ini_options]
-addopts = "--tb=short --no-header --showlocals --doctest-modules"
-doctest_optionflags = "ELLIPSIS NORMALIZE_WHITESPACE"
+addopts = [
+  "--tb=short",
+  "--no-header",
+  "--showlocals",
+  "--doctest-docutils-modules",
+  "-p no:doctest",
+  "--reruns=2"
+]
+doctest_optionflags = [
+  "ELLIPSIS",
+  "NORMALIZE_WHITESPACE"
+]
 testpaths = [
   "src/libvcs",
   "tests",

src/libvcs/_vendor/_structures.py

@@ -0,0 +1,63 @@
+# via https://github.com/pypa/packaging/blob/22.0/packaging/_structures.py
+# This file is dual licensed under the terms of the Apache License, Version
+# 2.0, and the BSD License. See the LICENSE file in the root of this repository
+# for complete details.
+from __future__ import annotations
+
+
+class InfinityType:
+    def __repr__(self) -> str:
+        return "Infinity"
+
+    def __hash__(self) -> int:
+        return hash(repr(self))
+
+    def __lt__(self, other: object) -> bool:
+        return False
+
+    def __le__(self, other: object) -> bool:
+        return False
+
+    def __eq__(self, other: object) -> bool:
+        return isinstance(other, self.__class__)
+
+    def __gt__(self, other: object) -> bool:
+        return True
+
+    def __ge__(self, other: object) -> bool:
+        return True
+
+    def __neg__(self: object) -> NegativeInfinityType:
+        return NegativeInfinity
+
+
+Infinity = InfinityType()
+
+
+class NegativeInfinityType:
+    def __repr__(self) -> str:
+        return "-Infinity"
+
+    def __hash__(self) -> int:
+        return hash(repr(self))
+
+    def __lt__(self, other: object) -> bool:
+        return True
+
+    def __le__(self, other: object) -> bool:
+        return True
+
+    def __eq__(self, other: object) -> bool:
+        return isinstance(other, self.__class__)
+
+    def __gt__(self, other: object) -> bool:
+        return False
+
+    def __ge__(self, other: object) -> bool:
+        return False
+
+    def __neg__(self: object) -> InfinityType:
+        return Infinity
+
+
+NegativeInfinity = NegativeInfinityType()