Git Integration
===============

Plugins access git via :attr:`~forkbit_sdk.BasePlugin.git` — a
:class:`~forkbit_sdk.GitClient` instance scoped to the current project.
Git is only available if the project directory contains a ``.git`` folder.

Tag and push on publish
-----------------------

.. code-block:: python

   def _on_publish(self) -> None:
       version = self.version_input.text().strip()
       if not version:
           self.notify("Please enter a version number.", level="warning")
           return

       # Save notes first
       all_notes = self.read_json("notes.json")
       all_notes[version] = {
           "text": self.editor.toPlainText(),
           "published": True,
       }
       self.write_json("notes.json", all_notes)

       # Create git tag if enabled in settings
       if self.settings.get("auto_tag", True):
           try:
               tag_name = f"v{version}"
               self.git.create_tag(tag_name, message=self.editor.toPlainText())
               self.git.push()
               self.notify(f"Published {tag_name} and pushed to remote.", level="success")
           except Exception as e:
               self.notify(f"Git error: {e}", level="error")
       else:
           self.notify(f"Published v{version}.", level="success")

Available operations
--------------------

.. list-table::
   :header-rows: 1

   * - Method
     - Description
   * - :meth:`~forkbit_sdk.GitClient.status`
     - Working tree status (dict of path to flags)
   * - :meth:`~forkbit_sdk.GitClient.current_branch`
     - Name of the current branch
   * - :meth:`~forkbit_sdk.GitClient.list_tags`
     - All tags in the repository
   * - :meth:`~forkbit_sdk.GitClient.create_tag`
     - Create an annotated tag
   * - :meth:`~forkbit_sdk.GitClient.commit`
     - Stage files and create a commit
   * - :meth:`~forkbit_sdk.GitClient.push`
     - Push to a remote
   * - :meth:`~forkbit_sdk.GitClient.pull`
     - Pull from the tracking remote

Error handling
--------------

All git methods raise :exc:`~forkbit_sdk.GitError` on failure. If git is
not available for the project (no ``.git`` directory), every call raises
``GitError("Git not available for this project")``.

.. code-block:: python

   from forkbit_sdk import GitError

   try:
       branch = self.git.current_branch()
   except GitError:
       branch = "(no git)"

Next: :doc:`translation`.