vcs.git

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

GitRepository

Interface to a Git Repository.

Attributes

Git_Cmd

GIT_LOG_STREAM

logger

HEAD

FETCH_HEAD

vcs.git.Git_Cmd
vcs.git.GIT_LOG_STREAM: GIT_LOG_STREAM_VALUE
vcs.git.logger
vcs.git.HEAD: Final = 'HEAD'
vcs.git.FETCH_HEAD: Final = 'FETCH_HEAD'
exception vcs.git.GitError(message: str, origin: str, process: e3.os.process.Run | None = None)

Bases: e3.vcs.VCSError

Exception raised by functions defined in E3.

class vcs.git.GitRepository(working_tree: str)

Interface to a Git Repository.

Variables:

  • git – path to the git binary

  • log_stream – stream where the log commands will be redirected (default is stdout)

  • working_tree – path to the git working tree

git: str | None
log_stream: TextIO | IO[str]
classmethod create(repo_path: str, initial_content_path: str | None = None) → str

Create a local Git repository.

Parameters:

  • repo_path – a local directory where to create the repository

  • initial_content_path – directory containing the initial content of the repository. If set to None an empty repository is created.

Returns:

the URL of the newly created repository

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.

Parameters:

  • cmd – the command line as a list of string, all None entries will be discarded

  • output – see e3.os.process.Run, by default it is the log_stream class attribute.

init(url: str | None = None, remote: str | None = 'origin') → None

Initialize a new Git repository and configure the remote.

Parameters:

  • url – url of the remote repository, if None create a local git repository

  • remote – name of the remote to create

Raise:

GitError

checkout(branch: str, force: bool = False) → None

Checkout a given refspec.

Parameters:

  • branch – name of the branch to checkout

  • force – throw away local changes if needed

Raise:

GitError

describe(commit: str = HEAD) → str

Get a human friendly revision for the given refspec.

Parameters:

commit – commit object to describe.

Returns:

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

write_local_diff(stream: IO[str]) → None

Write local changes in the working tree in stream.

Parameters:

stream – an open file descriptor

Raise:

GitError

write_diff(stream: IO[bytes], commit: str) → None

Write commit diff in stream.

Parameters:

  • commit – revision naming a commit object, e.g. sha1 or symbolic refname

  • stream – an open file descriptor

Raise:

GitError

fetch(url: str, refspec: str | None = None) → None

Fetch remote changes.

Parameters:

  • url – url of the remote repository

  • refspec – specifies which refs to fetch and which local refs to update.

Raise:

GitError

update(url: str, refspec: str, force: bool = False) → None

Fetch remote changes and checkout FETCH_HEAD.

Parameters:

  • url – url of the remote repository

  • refspec – specifies which refs to fetch and which local refs to update.

  • force – throw away local changes if needed

Raise:

GitError

fetch_gerrit_notes(url: str) → None

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

Parameters:

url – url of the remote repository

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.

Parameters:

  • stream – an open stream where to write the log content

  • max_count – max number of commit to display

  • rev_range – git revision range, see git log -h for details

  • with_gerrit_notes – if True also fetch Gerrit notes containing review data such as Submitted-at, Submitted-by.

Raise:

GitError

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.

Parameters:

  • stream – stream of text to read

  • max_diff_size – max size of a diff, if <= 0 diff are ignored

Returns:

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.

rev_parse(refspec: str = HEAD) → str

Get the sha associated to a given refspec.

Parameters:

refspec – refspec.

Raise:

GitError