plesty.server.services.gitbin
=============================

.. py:module:: plesty.server.services.gitbin

.. autoapi-nested-parse::

   Finding a ``git`` executable — and putting one on a bench that has none.

   Installing a device module from its repository needs ``git``. A Windows lab
   PC usually has none: git is not part of Windows, installing it system-wide is
   an administrator's job, and the person at the bench is rarely one. So the
   bench keeps its own — the portable MinGit archive git-for-windows publishes,
   unpacked into ``<home>/tools/git`` and run from there. No installer, no PATH
   change, no administrator; fetched once, verified against the digest pinned in
   ``config.yaml``, and found again on every later run.

   A POSIX bench is told to install git instead. There it is one package-manager
   command, and system-wide is where it belongs.



Attributes
----------

.. autoapisummary::

   plesty.server.services.gitbin.AUTO_ENV
   plesty.server.services.gitbin.GIT_DIR
   plesty.server.services.gitbin.ARCHITECTURES
   plesty.server.services.gitbin.Fetcher
   plesty.server.services.gitbin.Echo
   plesty.server.services.gitbin.POSIX_GIT_DIRECTORIES


Exceptions
----------

.. autoapisummary::

   plesty.server.services.gitbin.GitUnavailable


Functions
---------

.. autoapisummary::

   plesty.server.services.gitbin.auto_install_enabled
   plesty.server.services.gitbin.bench_git
   plesty.server.services.gitbin.find_git
   plesty.server.services.gitbin._candidates
   plesty.server.services.gitbin.install_git
   plesty.server.services.gitbin._download
   plesty.server.services.gitbin._unpack


Module Contents
---------------

.. py:data:: AUTO_ENV
   :value: 'PLESTY_SERVER_AUTO_GIT'


.. py:data:: GIT_DIR
   :value: 'git'


.. py:data:: ARCHITECTURES

.. py:data:: Fetcher

.. py:data:: Echo

.. py:exception:: GitUnavailable

   Bases: :py:obj:`RuntimeError`


   No ``git`` on the bench, and none could be installed.

   Initialize self.  See help(type(self)) for accurate signature.


.. py:function:: auto_install_enabled() -> bool

   Whether a missing ``git`` may be fetched (:data:`AUTO_ENV`, else the packaged default).


.. py:function:: bench_git(home: plesty.server.model.home.Home) -> pathlib.Path

   Where the bench keeps its own git (whether or not one is there yet).


.. py:function:: find_git(home: plesty.server.model.home.Home) -> str | None

   A usable ``git``: ``PATH`` first, then the usual installs, then the bench's own.

   :param home: The bench home, which may hold a git of its own.

   :returns: The executable, or ``None`` when the bench has none.


.. py:data:: POSIX_GIT_DIRECTORIES
   :value: ('/usr/bin', '/usr/local/bin', '/opt/homebrew/bin')


.. py:function:: _candidates(home: plesty.server.model.home.Home) -> collections.abc.Iterator[pathlib.Path]

   Paths a git may sit at without being on ``PATH``, best first.


.. py:function:: install_git(home: plesty.server.model.home.Home, echo: Echo | None = None, fetch: Fetcher | None = None) -> str

   Unpack a portable git into ``<home>/tools/git``; returns the executable.

   Windows only: it is the platform where a bench routinely has no git and no
   way to install one. The archive is verified against the pinned digest
   before anything is unpacked — a mismatch is an error, not a warning.

   :param home: The bench home to install into.
   :param echo: Where progress lines go.
   :param fetch: Reads the archive URL; injected by tests.

   :raises GitUnavailable: Not Windows, unknown architecture, download failed,
       digest mismatch, or the archive held no ``git``.


.. py:function:: _download(url: str, timeout: float = 300.0) -> bytes

   GET *url* into memory (tens of MB), with the standard library.


.. py:function:: _unpack(archive: bytes, target: pathlib.Path) -> None

   Extract the verified zip *archive* into *target*.

   :raises GitUnavailable: When the archive is not a readable zip.