Fix #118: Provide project Git config file (#120)

To create a reproducible build environment, we can't rely on the system
or user Git config. Depending on the options, it may let Git behave slightly
different than we expect.

For this reason, we need to ensure that we use project Git config that
is used whenever we call "git".

Author: tomschr

changelog.d/118.bugfix.rst

@@ -0,0 +1 @@
+Provide a project-defined Git config to prevent issues with user Git config.

pyproject.toml

@@ -99,7 +99,9 @@ docbuild = "docbuild.__main__:cli"
 package-dir = {"" = "src"}
 package-data = { "docbuild" = ["py.typed",
                                "config/xml/data/*.rnc",
-                               "config/xml/data/*.xsl"]}
+                               "config/xml/data/*.xsl",
+                               "etc/git/*"
+                               ]}
 include-package-data = true
 
 [tool.setuptools.dynamic]

src/docbuild/constants.py

@@ -145,6 +145,9 @@
 """The default filename for the environment's config file, typically
 used in production."""
 
+GIT_CONFIG_FILENAME = Path(__file__).parent / 'etc/git/gitconfig'
+"""The project-specific Git configuration file (relative to this project)"""
+
 # --- State and Logging Constants (Refactored) ---
 
 BASE_STATE_DIR = Path.home() / '.local' / 'state' / APP_NAME

src/docbuild/etc/git/gitconfig

@@ -0,0 +1,2 @@
+[docbuild]
+  name = docbuild-project

src/docbuild/utils/git.py

@@ -4,7 +4,7 @@
 from pathlib import Path
 from typing import ClassVar, Self
 
-from ..constants import GITLOGGER_NAME
+from ..constants import GIT_CONFIG_FILENAME, GITLOGGER_NAME
 from ..models.repo import Repo
 from ..utils.shell import execute_git_command
 
@@ -17,18 +17,24 @@ class ManagedGitRepo:
     #: Class variable to indicate the update state of a repo
     _is_updated: ClassVar[dict[Repo, bool]] = {}
 
-    def __init__(self: Self, remote_url: str, permanent_root: Path) -> None:
+    def __init__(self: Self,
+                 remote_url: str,
+                 permanent_root: Path,
+                 gitconfig: Path | None = None) -> None:
         """Initialize the managed repository.
 
         :param remote_url: The remote URL of the repository.
         :param permanent_root: The root directory for storing permanent bare clones.
+        :param gitconfig: The path to a separate Git configuration file
+           (=None, use the default config from etc/gitconfig)
         """
         self._repo_model = Repo(remote_url)
         self._permanent_root = permanent_root
         # The Repo model handles the "sluggification" of the URL
         self.bare_repo_path = self._permanent_root / self._repo_model.slug
         # Initialize attribute for output:
         self.stdout = self.stderr = None
+        self._gitconfig = gitconfig
         # Add repo into class variable
         type(self)._is_updated.setdefault(self._repo_model, False)
 
@@ -71,6 +77,7 @@ async def _initial_clone(self: Self) -> bool:
                 str(url),
                 str(self.bare_repo_path),
                 cwd=self._permanent_root,
+                gitconfig=self._gitconfig,
             )
             log.info("Cloned '%s' successfully", url)
             return True
@@ -133,7 +140,8 @@ async def create_worktree(
         clone_args.extend([str(self.bare_repo_path), str(target_dir)])
 
         self.stdout, self.stderr = await execute_git_command(
-            *clone_args, cwd=target_dir.parent
+            *clone_args, cwd=target_dir.parent,
+            gitconfig=self._gitconfig,
         )
 
     async def fetch_updates(self: Self) -> bool:
@@ -151,7 +159,9 @@ async def fetch_updates(self: Self) -> bool:
         log.info("Fetching updates for '%s'", self.slug)
         try:
             self.stdout, self.stderr = await execute_git_command(
-                'fetch', '--all', cwd=self.bare_repo_path
+                'fetch', '--all',
+                cwd=self.bare_repo_path,
+                gitconfig=self._gitconfig
             )
             log.info("Successfully fetched updates for '%s'", self.slug)
             return True

src/docbuild/utils/shell.py

@@ -4,7 +4,7 @@
 import logging
 from pathlib import Path
 
-from ..constants import GITLOGGER_NAME
+from ..constants import GIT_CONFIG_FILENAME, GITLOGGER_NAME
 
 log = logging.getLogger(GITLOGGER_NAME)
 
@@ -42,23 +42,29 @@ async def execute_git_command(
     *args: str,
     cwd: Path | None = None,
     extra_env: dict[str, str] | None = None,
+    gitconfig: Path | None = None,
 ) -> tuple[str, str]:
     """Execute a Git command asynchronously in a given directory.
 
     :param args: Command arguments for Git.
     :param cwd: The working directory for the Git command. If None, the
         current working directory is used.
     :param extra_env: Additional environment variables to set for the command.
+    :param gitconfig: The path to a separate Git configuration file. If None,
+        the default config from etc/git/gitconfig is used.
     :return: A tuple containing the decoded stdout and stderr of the command.
     :raises RuntimeError: If the command fails.
     :raises FileNotFoundError: If `cwd` is specified but does not exist.
     """
     if cwd and not cwd.is_dir():
         raise FileNotFoundError(f'Git working directory not found: {cwd}')
 
+    # Determine which config file to use
+    gconfig = gitconfig if gitconfig else GIT_CONFIG_FILENAME
+
     # Default Git arguments for consistent behavior
-    default_git_args = ('-c', 'color.ui=never')
-    command = ('git', *default_git_args, *args)
+    git_config_args = ('-c', 'color.ui=never')
+    command = ('git', *git_config_args, *args)
     log.debug('Executing Git command: %s in %s', ' '.join(command), cwd)
 
     # Default environment for secure and non-interactive execution
@@ -67,6 +73,9 @@ async def execute_git_command(
         'LC_ALL': 'C',
         'GIT_TERMINAL_PROMPT': '0',
         'GIT_PROGRESS_FORCE': '1',
+        'GIT_CONFIG_SYSTEM': '/dev/null',
+        # 'GIT_CONFIG_NOSYSTEM': '1',  # For older Git versions
+        'GIT_CONFIG_GLOBAL': str(gconfig),
     }
 
     # Merge environments, allowing kwargs to override defaults

tests/utils/test_git.py

@@ -60,6 +60,7 @@ async def test_managed_repo_clone_bare_new(
         'http://a.b/c.git',
         str(repo.bare_repo_path),
         cwd=tmp_path,
+        gitconfig=None,
     )
 
 
@@ -73,7 +74,12 @@ async def test_managed_repo_clone_bare_exists(
 
     result = await repo.clone_bare()
 
-    mock_execute_git.assert_awaited_once_with('fetch', '--all', cwd=repo.bare_repo_path)
+    mock_execute_git.assert_awaited_once_with(
+        'fetch',
+        '--all',
+        cwd=repo.bare_repo_path,
+        gitconfig=None,
+    )
 
 
 async def test_managed_repo_clone_bare_failure(
@@ -109,6 +115,7 @@ async def test_managed_repo_create_worktree_success(
         str(repo.bare_repo_path),
         str(target_dir),
         cwd=target_dir.parent,
+        gitconfig=None,
     )
 
 
@@ -133,6 +140,7 @@ async def test_managed_repo_create_worktree_with_options(
         str(repo.bare_repo_path),
         str(target_dir),
         cwd=target_dir.parent,
+        gitconfig=None,
     )
 
 
@@ -170,6 +178,7 @@ async def test_managed_repo_create_worktree_not_local(
         str(repo.bare_repo_path),
         str(target_dir),
         cwd=target_dir.parent,
+        gitconfig=None,
     )
 
 
@@ -222,7 +231,9 @@ async def test_fetch_updates_success(
     result = await repo.fetch_updates()
 
     assert result is True
-    mock_execute_git.assert_awaited_once_with('fetch', '--all', cwd=repo.bare_repo_path)
+    mock_execute_git.assert_awaited_once_with(
+        'fetch', '--all', cwd=repo.bare_repo_path, gitconfig=None
+    )
 
 
 async def test_fetch_updates_no_repo(
@@ -272,6 +283,7 @@ async def test_managed_repo_clone_bare_already_processed(
         'http://a.b/c.git',
         str(repo.bare_repo_path),
         cwd=tmp_path,
+        gitconfig=None,
     )
 
     # Second call, should do nothing because it's already processed

tests/utils/test_shell.py

@@ -0,0 +1,62 @@
+"""Tests for shell command utilities."""
+
+from pathlib import Path
+
+import pytest
+
+from docbuild.constants import GIT_CONFIG_FILENAME
+from docbuild.utils.shell import execute_git_command
+
+
+async def test_execute_git_command_with_gitconfig(tmp_path):
+    """Verify that execute_git_command uses the config file provided in the
+    `gitconfig` parameter to replace the user's configuration.
+    """
+    # The tmp_path fixture provides a temporary directory as a Path object
+    repo_path = tmp_path
+
+    # Initialize a Git repository in the temporary directory
+    await execute_git_command("init", cwd=repo_path)
+
+    # Create a project-specific gitconfig file
+    config_content = "[user]\n    name = Test User From Project Config\n"
+    project_config_path = repo_path / ".gitconfig"
+    project_config_path.write_text(config_content)
+
+    # Execute 'git config' to read the value, passing the project config
+    stdout, _ = await execute_git_command(
+        "config", "--get", "user.name", cwd=repo_path, gitconfig=project_config_path
+    )
+
+    # Assert that the output matches the value from our project-specific config
+    assert stdout == "Test User From Project Config"
+
+
+async def test_execute_git_command_without_gitconfig(tmp_path):
+    """
+    Verify that execute_git_command falls back to the default GIT_CONFIG_FILENAME
+    when the `gitconfig` parameter is not provided.
+    """
+    repo_path = tmp_path
+
+    # Execute 'git config' to read the value from our default config file.
+    # We call it without the `gitconfig` parameter to test the default behavior.
+    stdout, _ = await execute_git_command(
+        "config", "--get", "docbuild.name", cwd=repo_path
+    )
+
+    # This asserts that the value from 'etc/git/gitconfig' is read correctly.
+    assert stdout == "docbuild-project"
+
+
+async def test_execute_git_command_with_nonexistent_cwd():
+    with pytest.raises(FileNotFoundError):
+        stdout, _ = await execute_git_command(
+            'config', '--get', 'docbuild.name', cwd=Path("does-not-exist")
+        )
+
+async def test_execute_git_command_with_failed_command():
+    with pytest.raises(RuntimeError):
+        stdout, _ = await execute_git_command(
+            'foo',  # wrong git command
+        )