pytest_plugin(rename) gitconfig/hgconfig fixtures → vcs_-prefixed (#528)

why: The unprefixed `gitconfig`/`hgconfig` fixture names in libvcs's
pytest plugin collided with the third-party pytest-gitconfig plugin,
which exposes a `gitconfig` fixture returning a GitConfig helper
rather than a pathlib.Path. When both plugins auto-loaded, downstream
tests (e.g. python-copier on AUR) crashed with
`AttributeError: 'PosixPath' object has no attribute 'set'`.

what:
- Rename `gitconfig` → `vcs_gitconfig`, `set_gitconfig` → `set_vcs_gitconfig`
- Rename `hgconfig` → `vcs_hgconfig`, `set_hgconfig` → `set_vcs_hgconfig`
- Update internal callers: git_repo, hg_repo, git_remote_repo,
  create_hg_remote_repo, hg_remote_repo, doctest fixture harness
- Update root conftest.py autouse setup
- Update libvcs's own test suite (test_pytest_plugin, test_git submodule,
  test_hg url + sync autouse aliases)
- Update docs/api/pytest-plugin.md
- CHANGES entry under 0.41.x as a Breaking change

No deprecation alias is provided -- registering the old names as
aliases would still occupy the shared namespace and defeat the
deconfliction with pytest-gitconfig. Downstreams must update parameter
names.

Author: tony

CHANGES

@@ -20,6 +20,26 @@ $ uv add libvcs --prerelease allow
 _Notes on the upcoming release will go here._
 <!-- END PLACEHOLDER - ADD NEW CHANGELOG ENTRIES BELOW THIS LINE -->
 
+### Breaking changes
+
+#### pytest plugin: Rename `gitconfig` / `hgconfig` fixtures (#528)
+
+The pytest plugin's `gitconfig`, `set_gitconfig`, `hgconfig`, and
+`set_hgconfig` fixtures are renamed to `vcs_gitconfig`,
+`set_vcs_gitconfig`, `vcs_hgconfig`, and `set_vcs_hgconfig`
+respectively, matching the existing `vcs_name` / `vcs_email` / `vcs_user`
+convention.
+
+The unprefixed names collided with the third-party
+[`pytest-gitconfig`](https://pypi.org/project/pytest-gitconfig/) plugin,
+which exposes a `gitconfig` fixture returning a `GitConfig` helper
+rather than a `pathlib.Path`. When both plugins auto-loaded, downstream
+tests crashed with `AttributeError: 'PosixPath' object has no attribute 'set'`.
+
+No deprecation alias is provided -- the entire point of the rename is
+to vacate the shared name. Downstream test suites that referenced the
+old fixture names must update parameter names accordingly.
+
 ### Bug fixes
 
 - Fix dark-theme flash when light theme is selected — the docs

conftest.py

@@ -42,7 +42,7 @@ def cwd_default(monkeypatch: pytest.MonkeyPatch, tmp_path: pathlib.Path) -> None
 @pytest.fixture(autouse=True)
 def setup(
     request: pytest.FixtureRequest,
-    gitconfig: pathlib.Path,
+    vcs_gitconfig: pathlib.Path,
     set_home: pathlib.Path,
 ) -> None:
     """Configure test fixtures for pytest."""

docs/api/pytest-plugin.md

@@ -16,8 +16,8 @@ and home-directory setup without repeating bootstrap code in every suite.
 These fixtures are the usual starting point when enabling the plugin:
 
 - {fixture}`set_home` patches `$HOME` to point at {fixture}`user_path`.
-- {fixture}`set_gitconfig` and {fixture}`set_hgconfig` apply stable VCS
-  configuration.
+- {fixture}`set_vcs_gitconfig` and {fixture}`set_vcs_hgconfig` apply stable
+  VCS configuration.
 - {fixture}`vcs_name`, {fixture}`vcs_email`, and {fixture}`vcs_user` let you
   override commit identity defaults.
 - {fixture}`git_commit_envvars` helps when Git ignores `GIT_CONFIG` in a
@@ -35,8 +35,8 @@ import pytest
 @pytest.fixture(autouse=True)
 def setup(
     set_home: None,
-    set_gitconfig: None,
-    set_hgconfig: None,
+    set_vcs_gitconfig: None,
+    set_vcs_hgconfig: None,
 ) -> None:
     pass
 ```

src/libvcs/pytest_plugin.py

@@ -69,8 +69,8 @@ def vcs_user(vcs_name: str, vcs_email: str) -> str:
 def git_commit_envvars(vcs_name: str, vcs_email: str) -> GitCommitEnvVars:
     """Return environment variables for `git commit`.
 
-    For some reason, `GIT_CONFIG` via {func}`set_gitconfig` doesn't work for `git
-    commit`.
+    For some reason, `GIT_CONFIG` via {func}`set_vcs_gitconfig` doesn't work for
+    `git commit`.
     """
     return {
         "GIT_AUTHOR_NAME": vcs_name,
@@ -146,7 +146,7 @@ def set_home(
 
 @pytest.fixture(scope="session")
 @skip_if_git_missing
-def gitconfig(
+def vcs_gitconfig(
     user_path: pathlib.Path,
     vcs_email: str,
     vcs_name: str,
@@ -174,19 +174,19 @@ def gitconfig(
 
 @pytest.fixture
 @skip_if_git_missing
-def set_gitconfig(
+def set_vcs_gitconfig(
     monkeypatch: pytest.MonkeyPatch,
-    gitconfig: pathlib.Path,
+    vcs_gitconfig: pathlib.Path,
 ) -> pathlib.Path:
     """Set git configuration."""
-    monkeypatch.setenv("GIT_CONFIG", str(gitconfig))
-    monkeypatch.setenv("GIT_CONFIG_GLOBAL", str(gitconfig))  # For child processes
-    return gitconfig
+    monkeypatch.setenv("GIT_CONFIG", str(vcs_gitconfig))
+    monkeypatch.setenv("GIT_CONFIG_GLOBAL", str(vcs_gitconfig))  # For child processes
+    return vcs_gitconfig
 
 
 @pytest.fixture(scope="session")
 @skip_if_hg_missing
-def hgconfig(
+def vcs_hgconfig(
     user_path: pathlib.Path,
     vcs_user: str,
 ) -> pathlib.Path:
@@ -210,13 +210,13 @@ def hgconfig(
 
 @pytest.fixture
 @skip_if_hg_missing
-def set_hgconfig(
+def set_vcs_hgconfig(
     monkeypatch: pytest.MonkeyPatch,
-    hgconfig: pathlib.Path,
+    vcs_hgconfig: pathlib.Path,
 ) -> pathlib.Path:
     """Set Mercurial configuration."""
-    monkeypatch.setenv("HGRCPATH", str(hgconfig))
-    return hgconfig
+    monkeypatch.setenv("HGRCPATH", str(vcs_hgconfig))
+    return vcs_hgconfig
 
 
 @pytest.fixture
@@ -458,7 +458,7 @@ def git_remote_repo_single_commit_post_init(
 @skip_if_git_missing
 def git_remote_repo(
     create_git_remote_repo: CreateRepoFn,
-    gitconfig: pathlib.Path,
+    vcs_gitconfig: pathlib.Path,
     git_commit_envvars: GitCommitEnvVars,
 ) -> pathlib.Path:
     """Copy the session-scoped Git repository to a temporary directory."""
@@ -649,7 +649,7 @@ def empty_hg_repo(
 def create_hg_remote_repo(
     remote_repos_path: pathlib.Path,
     empty_hg_repo: pathlib.Path,
-    hgconfig: pathlib.Path,
+    vcs_hgconfig: pathlib.Path,
 ) -> CreateRepoFn:
     """Pre-made hg repo, bare, used as a file:// remote to checkout and commit to."""
 
@@ -668,7 +668,7 @@ def fn(
         if remote_repo_post_init is not None and callable(remote_repo_post_init):
             remote_repo_post_init(
                 remote_repo_path=remote_repo_path,
-                env={"HGRCPATH": str(hgconfig)},
+                env={"HGRCPATH": str(vcs_hgconfig)},
             )
 
         assert empty_hg_repo.exists()
@@ -685,13 +685,13 @@ def fn(
 def hg_remote_repo(
     remote_repos_path: pathlib.Path,
     create_hg_remote_repo: CreateRepoFn,
-    hgconfig: pathlib.Path,
+    vcs_hgconfig: pathlib.Path,
 ) -> pathlib.Path:
     """Pre-made, file-based repo for push and pull."""
     repo_path = create_hg_remote_repo()
     hg_remote_repo_single_commit_post_init(
         remote_repo_path=repo_path,
-        env={"HGRCPATH": str(hgconfig)},
+        env={"HGRCPATH": str(vcs_hgconfig)},
     )
     return repo_path
 
@@ -701,7 +701,7 @@ def git_repo(
     remote_repos_path: pathlib.Path,
     projects_path: pathlib.Path,
     git_remote_repo: pathlib.Path,
-    set_gitconfig: pathlib.Path,
+    set_vcs_gitconfig: pathlib.Path,
     set_home: None,  # Needed for child processes (e.g. submodules)
 ) -> GitSync:
     """Pre-made git clone of remote repo checked out to user's projects dir."""
@@ -736,7 +736,7 @@ def hg_repo(
     remote_repos_path: pathlib.Path,
     projects_path: pathlib.Path,
     hg_remote_repo: pathlib.Path,
-    set_hgconfig: pathlib.Path,
+    set_vcs_hgconfig: pathlib.Path,
 ) -> HgSync:
     """Pre-made hg clone of remote repo checked out to user's projects dir."""
     remote_repo_name = unique_repo_name(remote_repos_path=projects_path)
@@ -791,7 +791,7 @@ def add_doctest_fixtures(
     tmp_path: pathlib.Path,
     set_home: pathlib.Path,
     git_commit_envvars: GitCommitEnvVars,
-    hgconfig: pathlib.Path,
+    vcs_hgconfig: pathlib.Path,
     create_git_remote_repo: CreateRepoFn,
     create_svn_remote_repo: CreateRepoFn,
     create_hg_remote_repo: CreateRepoFn,
@@ -826,6 +826,6 @@ def add_doctest_fixtures(
             create_hg_remote_repo,
             remote_repo_post_init=functools.partial(
                 hg_remote_repo_single_commit_post_init,
-                env={"HGRCPATH": str(hgconfig)},
+                env={"HGRCPATH": str(vcs_hgconfig)},
             ),
         )

tests/cmd/test_git.py

@@ -2339,7 +2339,7 @@ def test_reflog_entry_delete(git_repo: GitSync) -> None:
 def submodule_repo(
     tmp_path: pathlib.Path,
     git_commit_envvars: GitCommitEnvVars,
-    set_gitconfig: pathlib.Path,
+    set_vcs_gitconfig: pathlib.Path,
 ) -> git.Git:
     """Create a git repository to use as a submodule source."""
     # Create a repo to serve as submodule source

tests/sync/test_hg.py

@@ -23,11 +23,11 @@
 
 
 @pytest.fixture(autouse=True)
-def set_hgconfig(
-    set_hgconfig: pathlib.Path,
+def set_vcs_hgconfig(
+    set_vcs_hgconfig: pathlib.Path,
 ) -> pathlib.Path:
     """Set mercurial configuration."""
-    return set_hgconfig
+    return set_vcs_hgconfig
 
 
 def test_hg_sync(

tests/test_pytest_plugin.py

@@ -46,11 +46,11 @@ def test_create_svn_remote_repo(
 
 
 def test_gitconfig(
-    gitconfig: pathlib.Path,
-    set_gitconfig: pathlib.Path,
+    vcs_gitconfig: pathlib.Path,
+    set_vcs_gitconfig: pathlib.Path,
     vcs_email: str,
 ) -> None:
-    """Test gitconfig fixture."""
+    """Test vcs_gitconfig fixture."""
     output = run(["git", "config", "--get", "user.email"])
     used_config_file_output = run(
         [
@@ -61,7 +61,7 @@ def test_gitconfig(
             "user.email",
         ],
     )
-    assert str(gitconfig) in used_config_file_output
+    assert str(vcs_gitconfig) in used_config_file_output
     assert vcs_email in output, "Should use our fixture config and home directory"
 
 
@@ -97,7 +97,7 @@ def vcs_email() -> str:
 @pytest.fixture(autouse=True)
 def setup(
     request: pytest.FixtureRequest,
-    gitconfig: pathlib.Path,
+    vcs_gitconfig: pathlib.Path,
     set_home: pathlib.Path,
 ) -> None:
     pass
@@ -183,12 +183,12 @@ def test_git_bare_repo_sync_and_commit(
 
 @pytest.mark.skipif(not shutil.which("git"), reason="git is not available")
 def test_gitconfig_submodule_file_protocol(
-    gitconfig: pathlib.Path,
+    vcs_gitconfig: pathlib.Path,
     user_path: pathlib.Path,
     tmp_path: pathlib.Path,
     monkeypatch: pytest.MonkeyPatch,
 ) -> None:
-    """Test that gitconfig fixture allows file:// protocol for git submodule operations.
+    """Test that vcs_gitconfig fixture allows file:// protocol for submodule operations.
 
     Git submodule operations spawn child processes that don't inherit local repo config.
     The child `git clone` process needs protocol.file.allow=always in global config.
@@ -201,7 +201,7 @@ def test_gitconfig_submodule_file_protocol(
 
     See: https://github.com/vcs-python/libvcs/issues/509
     """
-    # Isolate git config: use fixture's gitconfig via HOME, block only system config
+    # Isolate git config: use fixture's vcs_gitconfig via HOME, block only system config
     # Note: We don't block GIT_CONFIG_GLOBAL because git falls back to $HOME/.gitconfig
     # when GIT_CONFIG_GLOBAL is unset, which is where our fixture puts the config
     monkeypatch.setenv("HOME", str(user_path))
@@ -252,7 +252,7 @@ def test_gitconfig_submodule_file_protocol(
     # Assert: submodule add should succeed (no "fatal" errors)
     assert "fatal" not in result.stderr.lower(), (
         f"git submodule add failed with: {result.stderr}\n"
-        'This indicates gitconfig fixture is missing [protocol "file"] allow = always'
+        'vcs_gitconfig fixture is missing [protocol "file"] allow = always'
     )
     assert result.returncode == 0, f"git submodule add failed: {result.stderr}"
 
@@ -276,13 +276,13 @@ def test_git_repo_fixture_submodule_file_protocol(
     protocol.file.allow=always.
 
     The git_repo fixture depends on set_home to ensure child processes
-    (like git clone spawned by git submodule add) can find the test gitconfig.
+    (like git clone spawned by git submodule add) can find the test vcs_gitconfig.
 
     See: https://github.com/vcs-python/libvcs/issues/509
     """
     from libvcs.pytest_plugin import git_remote_repo_single_commit_post_init
 
-    # Verify that HOME is set to user_path where test gitconfig resides
+    # Verify that HOME is set to user_path where test vcs_gitconfig resides
     assert os.environ.get("HOME") == str(user_path), (
         f"git_repo fixture should set HOME to user_path.\n"
         f"Expected: {user_path}\n"

tests/url/test_hg.py

@@ -16,11 +16,11 @@
 
 
 @pytest.fixture(autouse=True)
-def set_hgconfig(
-    set_hgconfig: pathlib.Path,
+def set_vcs_hgconfig(
+    set_vcs_hgconfig: pathlib.Path,
 ) -> pathlib.Path:
     """Set mercurial configuration."""
-    return set_hgconfig
+    return set_vcs_hgconfig
 
 
 class HgURLFixture(typing.NamedTuple):