onyo.lib.git module

class onyo.lib.git.GitRepo(path, find_root=False)[source]

Bases: object

Representation of a git repository.

This relies on subprocesses running on a git worktree. Does not currently support bare repositories.

root

The absolute path to the root of the git worktree.

Type:: Path

__init__(path, find_root=False)[source]

Instantiates a GitRepo object with path as the root directory.

Parameters:

path (Path) – An absolute path to the root of a git repository.
find_root (bool (default: False)) – find_root=True allows to search the root of a git worktree from a subdirectory, beginning at path, instead of requiring the root.

check_ignore(ignore, paths)[source]

Get the paths that are matched by patterns defined in ignore.

This is utilizing git-check-ignore to evaluate paths against a file ignore, that defines exclude patterns the gitignore-way.

Parameters:

ignore (Path) – Path to a file containing exclude patterns to evaluate.
paths (list[Path]) – Paths to check against the patterns in ignore.

Returns:

Paths in paths that are excluded by the patterns in ignore.

Return type:

list of Path

clear_cache()[source]

Clear cache of this instance of GitRepo.

Caches cleared are: - GitRepo.files

If the repository is exclusively modified via public API functions, the cache of the GitRepo object is consistent. If the repository is modified otherwise, use of this function may be necessary to ensure that the cache does not contain stale information.

Return type:: None

commit(paths, message)[source]

Stage and commit changes in git.

Parameters:

paths (Union[Iterable[Path], Path]) – List of 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 on GitRepo.commit().

If changes are made by different means, use GitRepo.clear_cache() to reset the cache.

static find_root(path)[source]

Returns the git worktree root path belongs to.

Parameters:: path (Path) – The path to identify the git worktree root for. This can be any subdirectory of the repository, or the root directory itself.
Returns:: An absolute path to the root of the git worktree.
Return type:: Path
Raises:: OnyoInvalidRepoError – If path is not inside a git repository at all.

get_commit_msg(commitish=None)[source]

Returns the full commit message of a commit-ish.

Parameters:: commitish (str | None (default: None)) – Any identifier that refers to a commit (defaults to “HEAD”).
Returns:: the commit message including the subject line.
Return type:: str

get_config(name, file_=None)[source]

Get the value for a configuration option specified by name.

By default, git-config is read following its order of precedence (worktree, local, global, system). If a file_ is given, this is read instead.

Parameters:

name

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

[SECTION "NAME"]
  KEY = VALUE

file_

path to a config file to read instead of Git’s default locations.

returns:: The config value if it exists. None otherwise.
rtype:: str or None

get_hexsha(commitish=None, short=False)[source]

Return the hexsha of a given commit-ish.

Parameters:

commitish (str | None (default: None)) – Any identifier that refers to a commit (defaults to “HEAD”).
short (bool (default: False)) – Whether to return the abbreviated form of the hexsha.

Returns:

Hexsha of commitish. None, if querying the mother of all commits, i.e. ‘HEAD’ of an empty repository.

Return type:

str or None

Raises:

ValueError – If commit-ish is unknown.

get_subtrees(paths=None)[source]

Get tracked files in the subtrees rooted at paths.

Parameters:: paths (Optional[Iterable[Path]] (default: None)) – Roots of subtrees to consider. The entire worktree by default.
Returns:: Absolute paths to all tracked files within the given subtrees.
Return type:: list of Path

is_clean_worktree()[source]

Check whether the git worktree is clean.

Returns:: True if the git worktree is clean, otherwise False.
Return type:: bool

static is_git_path(path)[source]

Whether path is a git file or directory.

A ‘git path’ is considered a path that is used by git itself (tracked or not) and therefore not valid for use by onyo, e.g. .git/*, .gitignore, gitattributes, .gitmodules, etc. Any path underneath a directory called .git and any basename starting with .git returns False.

Parameters:: path (Path) – The path to check.
Returns:: True if path is a git file or directory, otherwise False.
Return type:: bool

maybe_init()[source]

Initialize self.root as a git repository if it is not already one.

Return type:: None

set_config(name, value, location=None)[source]

Set the configuration option name to value.

Parameters:

name (str) – The name of the configuration option to set.
value (str) – The value to set for the configuration option.
location (str | Path | None (default: None)) – The location of the configuration for which the value should be set. If a Path: config file to read, otherwise standard Git config locations: ‘system’, ‘global’, ‘local’, and ‘worktree’. None means git-config default behavior (‘local’). Default: None.

Raises:

ValueError – If location is unknown.

Return type:

None