pytest_plugin: rename gitconfig/hgconfig → vcs_-prefixed (#529)

Vacate the `gitconfig` / `hgconfig` pytest fixture names that
collided with the third-party `pytest-gitconfig` plugin. When both
plugins auto-loaded (e.g. via Arch's python-copier package using a
system-site-packages venv), downstream tests crashed with
`AttributeError: 'PosixPath' object has no attribute 'set'`.

Renames adopt the `vcs_` prefix already used by `vcs_name`,
`vcs_email`, and `vcs_user`:

- `gitconfig` → `vcs_gitconfig`
- `set_gitconfig` → `set_vcs_gitconfig`
- `hgconfig` → `vcs_hgconfig`
- `set_hgconfig` → `set_vcs_hgconfig`

**Breaking changes:** No deprecation alias is provided — registering
the old names would still occupy the shared namespace and defeat
the deconfliction. Downstream test suites that referenced the old
fixture names must update their parameter names.

Internal callers across the pytest plugin, root conftest, and
libvcs's own test suite are updated. `docs/api/pytest-plugin.md`,
`CHANGES`, `MIGRATION`, and `AGENTS.md` are kept in sync.

Fixes #528
See also: vcs-python/vcspull#548 (downstream coordination)

Author: tony

AGENTS.md

@@ -146,7 +146,7 @@ libvcs uses pytest for testing with many custom fixtures. The pytest plugin (`py
 - `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
+- `set_home`, `vcs_gitconfig`, `vcs_hgconfig`, `git_commit_envvars`: Environment fixtures
 
 These fixtures handle setup and teardown automatically, creating isolated test environments.
 

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

MIGRATION

@@ -24,6 +24,23 @@ _Notes on the upcoming release will be added here_
 
 <!-- Maintainers, insert migration notes for the next release here -->
 
+### pytest fixtures: `gitconfig` / `hgconfig` renamed to `vcs_gitconfig` / `vcs_hgconfig` (#528)
+
+- pytest: `gitconfig` renamed to `vcs_gitconfig`
+- pytest: `set_gitconfig` renamed to `set_vcs_gitconfig`
+- pytest: `hgconfig` renamed to `vcs_hgconfig`
+- pytest: `set_hgconfig` renamed to `set_vcs_hgconfig`
+
+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 -- update parameter names in test
+suites, conftests, and any embedded `pytester.makeconftest` text that
+references these fixtures.
+
 ### pytest fixtures: `git_local_clone` renamed to `example_git_repo` (#468)
 
 - pytest: `git_local_clone` renamed to `example_git_repo`

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):