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: Path | str, /, skip_checks: bool = False)

A class that allows interactions with a git repository.

Parameters:

• path – path to the repo root dir.

• skip_checks – don’t check if we’re inside a repo.

property path: Path

Path to the repo, as was passed to the constructor.

git(*args: str) → bytes

Call git and return its stdout.

root() → Path

Get the root directory of the repo.

git_dir() → Path

Get path to the .git directory of the repo.

status() → Status

Query the current repository status.

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

Query the log for given git objects.

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

show(ref: str, /) → Commit | None

Query information for the given git object.

Return None if object is not found.

tags() → List[str]

List all tags in this repository.

branches() → List[str]

List all branches in this repository.

remotes() → List[str]

List all remote branches in this repository.

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: str | None = None)

Commit description.

hash: str

Commit hash.

author: str

Author name.

author_email: str

Author email.

author_date: datetime

Author time.

committer: str

Committer name.

committer_email: str

Committer email.

committer_date: 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: str | None = 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 CommitParser.

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

Status of a working copy.

commit: str

Current commit hash.

branch: str | None = None

Name of the current branch.

upstream: str | None = None

Name of the upstream branch.

ahead: int | None = None

Number of commits the branch is ahead of upstream.

behind: int | None = 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[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: Path | None = None, staged: Modification = Modification.UNMODIFIED, tree: Modification = Modification.UNMODIFIED)

Status of a changed file.

path: Path

Path of the file.

path_from: Path | None = None

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

staged: Modification = '.'

File modification in the index (staged).

tree: Modification = '.'

File modification in the tree (unstaged).

class yuio.git.Modification(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

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. Use Ref in your type hints to help Yuio detect that you want to parse it as a git reference:

class yuio.git.Ref

A special kind of string that contains a git object reference.

Ref is not guaranteed to be valid; this type is used in type hints to make use of the RefParser.

alias of str

class yuio.git.Tag

A special kind of string that contains a tag name.

Ref is not guaranteed to be valid; this type is used in type hints to make use of the TagParser.

alias of str

class yuio.git.Branch

A special kind of string that contains a branch name.

Ref is not guaranteed to be valid; this type is used in type hints to make use of the BranchParser.

alias of str

class yuio.git.Remote

A special kind of string that contains a remote branch name.

Ref is not guaranteed to be valid; this type is used in type hints to make use of the RemoteParser.

alias of str

class yuio.git.RefParser(repo_path: Repo | str | Path | None = None, /, *, should_exist: bool = False)

A parser that provides autocompletion for git refs, but doesn’t verify anything else.

class yuio.git.TagParser(repo_path: Repo | str | Path | None = None, /, *, should_exist: bool = False)

A parser that checks if the given string is a valid tag name.

class yuio.git.BranchParser(repo_path: Repo | str | Path | None = None, /, *, should_exist: bool = False)

A parser that checks if the given string is a valid tag name.

class yuio.git.RemoteParser(repo_path: Repo | str | Path | None = None, /, *, should_exist: bool = False)

A parser that checks if the given string is a valid tag remote branch.

If you know path to your repository before hand, and want to make sure that the user supplies a valid ref that points to an existing git object, use CommitParser:

class yuio.git.CommitParser(repo: Repo)

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

This parser validates that the given ref exists in the given repository, parses it and returns a commit data associated with this ref.

If you need a simple string without additional validation, use RefParser.