Source code for forkbit_sdk.git_client

from __future__ import annotations




class GitError(Exception):
    """Raised when a git operation fails or git is not available."""





class GitClient:
    """Client for git operations on the current project.

    Available as :attr:`BasePlugin.git`. Only usable if the project
    directory contains a ``.git`` folder — otherwise all methods raise
    :exc:`GitError`.

    Example::

        tags = self.git.list_tags()
        self.git.create_tag("v1.0.0", message="Release 1.0.0")
        self.git.push()
    """



    def __init__(self, repo=None):
        self._repo = repo


    def _check(self):
        if not self._repo:
            raise GitError("Git not available for this project")



    def status(self) -> dict:
        """Return the working tree status.

        :returns: Dict mapping file paths to their status flags.
        :raises GitError: If git is not available.
        """
        self._check()
        return self._repo.status()




    def current_branch(self) -> str:
        """Return the name of the currently checked-out branch.

        :raises GitError: If git is not available.
        """
        self._check()
        return self._repo.current_branch()




    def create_tag(self, name: str, message: str = "") -> None:
        """Create an annotated git tag.

        :param name: Tag name (e.g. ``"v1.0.0"``).
        :param message: Optional tag message. If empty, a lightweight tag is created.
        :raises GitError: If git is not available.
        """
        self._check()
        self._repo.create_tag(name, message)




    def list_tags(self) -> list[str]:
        """Return all tags in the repository.

        :returns: List of tag names, sorted alphabetically.
        :raises GitError: If git is not available.
        """
        self._check()
        return self._repo.list_tags()




    def push(self, remote: str = "origin") -> None:
        """Push commits and tags to a remote.

        :param remote: Remote name (default: ``"origin"``).
        :raises GitError: If git is not available or the push fails.
        """
        self._check()
        self._repo.push(remote=remote)




    def pull(self) -> None:
        """Pull changes from the tracking remote.

        :raises GitError: If git is not available or the pull fails.
        """
        self._check()
        self._repo.pull()




    def commit(self, message: str, paths: list[str] | None = None) -> str:
        """Create a commit.

        :param message: Commit message.
        :param paths: Files to stage. If ``None``, commits all staged changes.
        :returns: The commit hash.
        :raises GitError: If git is not available or the commit fails.
        """
        self._check()
        return self._repo.commit(message, paths)