Git

This module provides basic functionality to interact with git. It comes in handy when writing deployment scripts.

Interacting with a repository

All repository interactions are done through the Repo class and its methods. If an interaction fails, a GitException is raised.

class yuio.git.Repo(path: Union[Path, str])

A class that allows interactions with a git repository.

git(*args: str) → bytes

Call git and return its stdout.

status() → Status

Query the current repository status.

log(*refs: str, max_entries: Optional[int] = 10) → List[Commit]

Query the log for given git objects.

Note that by default log output is limited by ten entries.

show(ref) → Optional[Commit]

Query information for the given git object.

Return None if object is not found.

class yuio.git.GitException

Raised when git returns a non-zero exit code.

Commit and status objects

Some of Repo commands return parsed descriptions of git objects:

class yuio.git.Commit(hash: str, author: str, author_email: str, author_date: datetime, committer: str, committer_email: str, committer_date: datetime, title: str, body: str, orig_ref: Optional[str] = None)

Commit description.

hash: str

Commit hash.

author: str

Author name.

author_email: str

Author email.

author_date: datetime.datetime

Author time.

committer: str

Committer name.

committer_email: str

Committer email.

committer_date: datetime.datetime

Committer time.

title: str

Commit title, i.e. first line of the message.

body: str

Commit body, i.e. the rest of the message.

orig_ref: Optional[str] = None

If commit was parsed from a user input, this field will contain original input. I.e. if a user enters HEAD and it gets resolved into a commit, orig_ref will contain string 'HEAD'.

See also RefParser.

class yuio.git.Status(commit: str, branch: ~typing.Optional[str] = None, upstream: ~typing.Optional[str] = None, ahead: ~typing.Optional[int] = None, behind: ~typing.Optional[int] = None, has_tracked_changes: bool = False, has_untracked_changes: bool = False, changes: ~typing.List[~yuio.git.FileStatus] = <factory>)

Status of a working copy.

branch: Optional[str] = None

Name of the current branch.

upstream: Optional[str] = None

Name of the upstream branch.

ahead: Optional[int] = None

Number of commits the branch is ahead of upstream.

behind: Optional[int] = None

Number of commits the branch is behind of upstream.

has_tracked_changes: bool = False

True if any tracked file was changed.

has_untracked_changes: bool = False

True if any file was added but not tracked.

changes: List[yuio.git.FileStatus]

List of changed files, both tracked and untracked.

property has_changes: bool

True if there are any changes in the repository.

class yuio.git.FileStatus(path: Path, path_from: Optional[Path] = None, staged: Modification = Modification.UNMODIFIED, tree: Modification = Modification.UNMODIFIED)

Status of a changed file.

path: pathlib.Path

Path of the file.

path_from: Optional[pathlib.Path] = None

If file was moved, contains path where it was moved from.

staged: yuio.git.Modification = '.'

File modification in the index (staged).

tree: yuio.git.Modification = '.'

File modification in the tree (unstaged).

class yuio.git.Modification(value)

For changed file, what modification was applied to it.

UNMODIFIED = '.'

File wasn’t changed.

MODIFIED = 'M'

File was changed.

ADDED = 'A'

File was created.

DELETED = 'D'

File was deleted.

RENAMED = 'R'

File was renamed (and possibly changed).

COPIED = 'C'

File was copied (and possibly changed).

UPDATED = 'U'

File with conflicts is unmerged.

IGNORED = '?'

File is in .gitignore.

UNTRACKED = '!'

File was created but not yet added to git, i.e. not staged.

Parsing git refs

When you need to query a git ref from a user, RefParser will ensure that the ref points to a valid git object:

class yuio.git.RefParser(repo: Repo)

A parser for git refs (commits, tags, branches, and so on).