onyo.lib.git module

class onyo.lib.git.GitRepo(path, find_root=False)

Bases: object

Representation of a Git repository.

Uses subprocess to execute git commands on a repository.

Bare repositories are not supported.

root

The absolute Path of the root of the git repository.

__init__(path, find_root=False)

Instantiate a GitRepo object with path as the root directory.

Parameters:

• path (Path) – The absolute Path of a git repository.

• find_root (bool (default: False)) – Replace path with the results of find_root(). Thus any directory of a git repository can be passed as path, not just the repo root.

check_ignore(ignore, paths)

Get the subset of paths that match patterns defined in ignore.

Parameters:

• ignore (Path) – Path to a file containing exclude patterns (in the style of .gitignore).

• paths (list[Path]) – Paths to check

Raises:

ValueError – Path is outside of the repository.

Return type:

list[Path]

clear_cache()

Clear the cache of this instance of GitRepo.

When the repository is modified using only the public API functions, the cache is consistent. This method is only necessary if the repository is modified otherwise.

Return type:

None

commit(paths, message)

Stage and commit changes in git.

Parameters:

• paths (Union[Iterable[Path], Path]) – Paths to commit.

• message (str) – The git commit message.

Return type:

None

property files: list[Path]

Get the absolute Paths of all tracked files.

This property is cached, and is reset automatically by commit().

static find_root(path)

Return the absolute path of the git worktree root that path belongs to.

Checks path itself and each of its parents.

Parameters:

path (Path) – The Path to find the git worktree root for.

Raises:

OnyoInvalidRepoError – Neither path nor its parents are a git repository.

Return type:

Path

get_commit_msg(commitish=None)

Return the full commit message of a commit-ish.

Parameters:

commitish (str | None (default: None)) – Any identifier that refers to a commit (defaults to “HEAD”).

Return type:

str

get_config(key, path=None)

Get the value of a configuration key.

If no path is given, the configuration key is acquired according to git-config’s order of precedence (worktree, local, global, system).

Parameters:

• key (str) –

  Name of the configuration key to query. Follows Git’s convention of “SECTION.NAME.KEY” to address a key in a git config file:

  [SECTION "NAME"]
      KEY = VALUE
  

• path (Path | None (default: None)) – Path of a config file, rather than Git’s default locations.

Return type:

str | None

get_files(paths=None)

Get the absolute Paths of all tracked files under paths.

Parameters:

paths (Optional[Iterable[Path]] (default: None)) – Paths to limit the scope of the search to. The entire repo by default.

Return type:

list[Path]

get_hexsha(commitish=None, short=False)

Return the hexsha of a given commit-ish.

Will return None if querying the mother of all commits (i.e. “HEAD” of an empty repository).

Parameters:

• commitish (str | None (default: None)) – Any identifier that refers to a commit (defaults to “HEAD”).

• short (bool (default: False)) – Return the abbreviated form of the hexsha.

Raises:

ValueError – commitish is unknown.

Return type:

str | None

history(path=None, n=None)

Yield commit dicts representing the history of path.

The history is acquired via git log (git log --follow if a path is given).

Parameters:

• path (Path | None (default: None)) – The Path to get the history of. Defaults to the repo root.

• n (int | None (default: None)) – Limit history to n commits. None for no limit (default).

Return type:

Generator[dict, None, None]

init_without_reinit()

Initialize self.root as a git repo, but not if it’s already one.

Return type:

None

is_clean_worktree()

Whether the git worktree is clean.

Return type:

bool

static is_git_path(path)

Whether path is a git file or directory.

A “git path” is a path that is used by git itself (tracked or not) and therefore not valid for use by Onyo.

Any path underneath a directory called .git and any basename starting with .git is considered a git path. e.g. .git/*, .gitignore, gitattributes, .gitmodules, etc.

Parameters:

path (Path) – The path to check.

Return type:

bool

set_config(key, value, location=None)

Set the value of a configuration key.

Parameters:

• key (str) – The name of the configuration key to set.

• value (str) – The value to set the configuration key to.

• location (Union[Literal['system', 'global', 'local', 'worktree'], Path, None] (default: None)) – The location to set the key/value in. Valid locations are standard git-config locations ('system', 'global', 'local', and 'worktree') or a Path of a file. None will use git-config’s default location ('local').

Raises:

ValueError – location is invalid.

Return type:

None