Repo resolver

repo_resolver ¶

This module supports all git operations for edk2-pytool-extensions.

edk2-pytool-extensions has consolidated all git functionality within the repo_resolver module, which relies on the GitPython PyPi module. This module provides functionality to clone, checkout, and clean repos and submodules along with providing common information about the repo or submodule.

The intent is to keep all git functionality consolidated in this module. Currently edk2_ci_setup.py, edk2_setup.py, and git_dependency.py use this module to perform git operations.

resolve ¶

resolve(
    file_system_path: os.PathLike,
    dependency: dict,
    force: bool = False,
    ignore: bool = False,
    update_ok: bool = False,
) -> None

Resolves a particular repo.

Parameters:

Name	Type	Description	Default
`file_system_path`	`Pathlike`	path to repo	required
`dependency`	`dict`	contains Path, Commit, Branch	required
`force`	`bool`	If it is OK to update the commit or branch	`False`
`ignore`	`bool`	If it is OK to ignore errors or not.	`False`
`update_ok`	`bool`	If it is OK to update the commit or branch	`False`

Raises:

Type	Description
`Exception`	An error resolving a repo and ignore=False

resolve_all ¶

resolve_all(
    workspace_path: os.PathLike,
    dependencies: list[dict],
    force: bool = False,
    ignore: bool = False,
    update_ok: bool = False,
    omnicache_dir: str = None,
) -> list[str]

Resolves all repos.

Parameters:

Name	Type	Description	Default
`workspace_path`	`osPathlike`	workspace root	required
`dependencies`	`list[dict]`	Dict contains Path, Commit, Branch	required
`force`	`bool`	If it is OK to update the commit or branch	`False`
`ignore`	`bool`	If it is OK to ignore errors or not.	`False`
`update_ok`	`bool`	If it is OK to update the commit or branch	`False`
`omnicache_dir`	`str`	Omnicache path, if used	`None`

Returns:

Type	Description
`list[str]`	list of paths to repos resolved

Raises:

Type	Description
`Exception`	An error resolving a repo and ignore=False

repo_details ¶

repo_details(abs_file_system_path: os.PathLike) -> dict

Return information about the repo.

if self.valid is False, all other return members are set to default values and should not be expected to be correct.

Parameters:

Name	Type	Description	Default
`abs_file_system_path`	`PathLike`	repo directory	required

Returns:

Type	Description
`dict`	dict containing details about the repository

clear_folder ¶

clear_folder(abs_file_system_path: os.PathLike) -> None

Cleans the folder.

Parameters:

Name	Type	Description	Default
`abs_file_system_path`	`PathLike`	Directory to delete.	required

process_submodules_from_ci_file ¶

process_submodules_from_ci_file(
    abs_file_system_path: os.PathLike, ci_file: str
) -> None

Processes the submodules of the repo.

Parameters:

Name	Type	Description	Default
`abs_file_system_path`	`PathLike`	Directory toplevel repo cloned in.	required
`ci_file`	`str`	str of path to the CI file relative to repo.	required

clone_repo ¶

clone_repo(
    abs_file_system_path: os.PathLike, DepObj: dict
) -> tuple

Clones the repo in the folder using the dependency object.

Parameters:

Name	Type	Description	Default
`abs_file_system_path`	`PathLike`	destination to clone	required
`DepObj`	`dict`	dict containing Commit, Full, Branch, etc	required

Returns:

Type	Description
`(PathLike, Bool)`	(destination, result)

checkout ¶

checkout(
    abs_file_system_path: str,
    dep: dict,
    update_ok: bool = False,
    ignore_dep_state_mismatch: bool = False,
    force: bool = False,
) -> None

Checks out a commit or branch.

Parameters:

Name	Type	Description	Default
`abs_file_system_path`	`PathLike`	The path to the repo	required
`dep`	`dict`	A dictionary containing a either a Commit or Branch, and also a Path	required
`update_ok`	`bool`	If it is OK to update the commit or branch	`False`
`ignore_dep_state_mismatch`	`bool`	Whether a mismatch will result in an exception or not.	`False`
`force`	`bool`	If it is OK to update the commit or branch	`False`

Raises:

Type	Description
`Exception`	dependency state mismatch if ignore_dep_state_mismatch = False
`GitCommandError`	If the commit or branch does not exist locally and on the remote

clean ¶

clean(
    abs_file_system_path: os.PathLike,
    ignore_files: Optional[list] = [],
) -> None

Resets and cleans the repo.

Parameters:

Name	Type	Description	Default
`abs_file_system_path`	`PathLike`	repo directory	required
`ignore_files`	`list`	list of files to ignore when performing a clean	`[]`

Raises:

Type	Description
`GitCommandError`	The command is invalid
`InvalidGitRepositoryError`	The repo is in an invalid format
`NoSuchPathError`	The path does not exist

submodule_clean ¶

submodule_clean(
    abs_file_system_path: os.PathLike, submodule: dict
) -> None

Resets and cleans a submodule of the repo.

Parameters:

Name	Type	Description	Default
`abs_file_system_path`	`PathLike`	repo directory	required
`submodule`	`dict`	object containing path (relative) attribute	required

Raises:

Type	Description
`GitCommandError`	The command is invalid
`InvalidGitRepositoryError`	The repo is in an invalid format
`NoSuchPathError`	The path does not exist
`ValueError`	submodule's path was invalid

submodule_resolve ¶

submodule_resolve(
    abs_file_system_path: os.PathLike,
    submodule: dict,
    omnicache_path: Optional[os.PathLike] = None,
) -> None

Resolves a submodule to the specified branch and commit in .gitmodules.

On the submodule, first performs a submodule sync followed by a submodule update --init.

Parameters:

Name	Type	Description	Default
`abs_file_system_path`	`PathLike`	repo directory	required
`submodule`	`dict`	object containing attributes: path (relative) and recursive	required
`omnicache_path`	`PathLike \| None`	absolute path to the omnicache, if used	`None`

Raises:

Type	Description
`GitCommandError`	The command is invalid
`InvalidGitRepositoryError`	The repo is in an invalid format
`NoSuchPathError`	The path does not exist

git_retry ¶

git_retry(
    attempts: int,
    func: Callable,
    *args: str,
    **kwargs: dict[str, any]
) -> any

Retry a function a given number of times before failing.

Parameters:

Name	Type	Description	Default
`attempts`	`int`	The number of times to retry the function	required
`func`	`Callable`	The function to call	required
`*args`	`str`	Arguments to pass to the function	`()`
`**kwargs`	`dict[str, any]`	Keyword arguments to pass to the function	`{}`

Returns:

Type	Description
`any`	The result of the function

Raises:

Type	Description
`Exception`	If the function fails after multiple retries