:py:mod:`vcs.git`
=================

.. py:module:: vcs.git

.. autoapi-nested-parse::

   High-Level interface to Git repository.

   Example::


       g = GitRepository(working_tree='/tmp/e3-core')
       g.init()
       g.update('ssh://git.adacore.com/anod', refspec='master', force=True)
       with open('/tmp/e3-core-log', 'w') as fd:
           g.write_log(fd, max_count=10)
       with open('/tmp/e3-core-log') as fd:
           authors = []
           for commit in g.parse_log(fd, max_diff_size=1024):
               authors.append(commit['email'])



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

Classes
~~~~~~~

.. autoapisummary::

   vcs.git.GitRepository




Attributes
~~~~~~~~~~

.. autoapisummary::

   vcs.git.Git_Cmd
   vcs.git.GIT_LOG_STREAM
   vcs.git.logger
   vcs.git.HEAD
   vcs.git.FETCH_HEAD


.. py:data:: Git_Cmd

   

.. py:data:: GIT_LOG_STREAM
   :type: GIT_LOG_STREAM_VALUE

   

.. py:data:: logger

   

.. py:data:: HEAD
   :type: Final
   :value: 'HEAD'

   

.. py:data:: FETCH_HEAD
   :type: Final
   :value: 'FETCH_HEAD'

   

.. py:exception:: GitError(message: str, origin: str, process: e3.os.process.Run | None = None)


   Bases: :py:obj:`e3.vcs.VCSError`

   Exception raised for Git operations errors.


.. py:class:: GitRepository(working_tree: str)


   Interface to a Git Repository.

   :cvar git: path to the git binary
   :cvar log_stream: stream where the log commands will be redirected
       (default is stdout)
   :ivar working_tree: path to the git working tree

   .. py:attribute:: git
      :type: str | None

      

   .. py:attribute:: log_stream
      :type: TextIO | IO[str]

      

   .. py:method:: create(repo_path: str, initial_content_path: str | None = None) -> str
      :classmethod:

      Create a local Git repository.

      :param repo_path: a local directory where to create the repository
      :param initial_content_path: directory containing the initial content
          of the repository. If set to None an empty repository is created.
      :return: the URL of the newly created repository


   .. py:method:: git_cmd(cmd: Git_Cmd, output: e3.os.process.DEVNULL_VALUE | e3.os.process.PIPE_VALUE | GIT_LOG_STREAM_VALUE | str | IO | None = GIT_LOG_STREAM, **kwargs: Any) -> e3.os.process.Run

      Run a git command.

      :param cmd: the command line as a list of string, all None entries will
          be discarded
      :param output: see e3.os.process.Run, by default it is the
          ``log_stream`` class attribute.
      :param kwargs: additional keyword arguments passed to e3.os.process.Run


   .. py:method:: init(url: str | None = None, remote: str | None = 'origin') -> None

      Initialize a new Git repository and configure the remote.

      :param url: url of the remote repository, if None create a local git
          repository
      :param remote: name of the remote to create
      :raise: GitError


   .. py:method:: checkout(branch: str, force: bool = False) -> None

      Checkout a given refspec.

      :param branch: name of the branch to checkout
      :param force: throw away local changes if needed
      :raise: GitError


   .. py:method:: describe(commit: str = HEAD) -> str

      Get a human friendly revision for the given refspec.

      :param commit: commit object to describe.
      :return: the most recent tag name with the number of additional commits
          on top of the tagged object and the abbreviated object name of the
          most recent commit (see `git help describe`).
      :raise: GitError


   .. py:method:: write_local_diff(stream: IO[str]) -> None

      Write local changes in the working tree in stream.

      :param stream: an open file descriptor
      :raise: GitError


   .. py:method:: write_diff(stream: IO[bytes], commit: str) -> None

      Write commit diff in stream.

      :param commit: revision naming a commit object, e.g. sha1 or symbolic
          refname
      :param stream: an open file descriptor
      :raise: GitError


   .. py:method:: fetch(url: str, refspec: str | None = None) -> None

      Fetch remote changes.

      :param url: url of the remote repository
      :param refspec: specifies which refs to fetch and which local refs to
          update.
      :raise: GitError


   .. py:method:: update(url: str, refspec: str, force: bool = False) -> None

      Fetch remote changes and checkout FETCH_HEAD.

      :param url: url of the remote repository
      :param refspec: specifies which refs to fetch and which local refs to
          update.
      :param force: throw away local changes if needed
      :raise: GitError


   .. py:method:: fetch_gerrit_notes(url: str) -> None

      Fetch notes generated by Gerrit in `refs/notes/review`.

      :param url: url of the remote repository


   .. py:method:: write_log(stream: IO[str], max_count: int = 50, rev_range: str | None = None, with_gerrit_notes: bool = False) -> None

      Write formatted log to a stream.

      :param stream: an open stream where to write the log content
      :param max_count: max number of commit to display
      :param rev_range: git revision range, see ``git log -h`` for details
      :param with_gerrit_notes: if True also fetch Gerrit notes containing
          review data such as Submitted-at, Submitted-by.
      :raise: GitError


   .. py:method:: parse_log(stream: IO[str], max_diff_size: int = 0) -> collections.abc.Iterator[dict[str, str | dict]]

      Parse a log stream generated with `write_log`.

      :param stream: stream of text to read
      :param max_diff_size: max size of a diff, if <= 0 diff are ignored
      :return: a generator returning commit information (directories with
          the following keys: sha, email, date, notes, message, diff). Note
          that the key diff is only set when max_diff_size is bigger than 0.
          The notes value is a dictionary built from the 'key:value' found in
          Gerrit notes.


   .. py:method:: rev_parse(refspec: str = HEAD) -> str

      Get the sha associated to a given refspec.

      :param refspec: refspec.
      :raise: GitError