GitRepositoryContext

The GitRepositoryContext captures the information of a Git repository. It can be created using the capsula.GitRepositoryContext.builder method or the capsula.GitRepositoryContext.__init__ method.

capsula.GitRepositoryContext.builder classmethod

builder(
    name: str | None = None,
    *,
    path: Path | str | None = None,
    path_relative_to_project_root: bool = False,
    allow_dirty: bool = True
) -> Callable[[CapsuleParams], GitRepositoryContext]

PARAMETER	DESCRIPTION
name	Name of the Git repository. If not provided, the name of the working directory will be used. TYPE: str | None DEFAULT: None
path	Path to the Git repository. If not provided, the parent directories of the file where the function is defined will be searched for a Git repository. TYPE: Path | str | None DEFAULT: None
path_relative_to_project_root	Whether path is relative to the project root. Will be ignored if path is None or absolute. If True, it will be interpreted as relative to the project root. If False, path will be interpreted as relative to the current working directory. It is recommended to set this to True in the configuration file. TYPE: bool DEFAULT: False
allow_dirty	Whether to allow the repository to be dirty TYPE: bool DEFAULT: True

Source code in capsula/_context/_git.py

@classmethod
def builder(
    cls,
    name: Annotated[
        str | None,
        Doc("Name of the Git repository. If not provided, the name of the working directory will be used."),
    ] = None,
    *,
    path: Annotated[
        Path | str | None,
        Doc(
            "Path to the Git repository. If not provided, the parent directories of the file where the function is "
            "defined will be searched for a Git repository.",
        ),
    ] = None,
    path_relative_to_project_root: Annotated[
        bool,
        Doc(
            "Whether `path` is relative to the project root. Will be ignored if `path` is None or absolute. "
            "If True, it will be interpreted as relative to the project root. "
            "If False, `path` will be interpreted as relative to the current working directory. "
            "It is recommended to set this to True in the configuration file.",
        ),
    ] = False,
    allow_dirty: Annotated[bool, Doc("Whether to allow the repository to be dirty")] = True,
) -> Callable[[CapsuleParams], GitRepositoryContext]:
    def build(params: CapsuleParams) -> GitRepositoryContext:
        if path_relative_to_project_root and path is not None and not Path(path).is_absolute():
            repository_path: Path | None = params.project_root / path
        else:
            repository_path = Path(path) if path is not None else None

        if repository_path is not None:
            repo = Repo(repository_path, search_parent_directories=False)
        else:
            if isinstance(params.exec_info, FuncInfo):
                repo_search_start_path = Path(inspect.getfile(params.exec_info.func)).parent
            elif isinstance(params.exec_info, CommandInfo) or params.exec_info is None:
                repo_search_start_path = Path.cwd()
            else:
                msg = f"exec_info must be an instance of FuncInfo or CommandInfo, not {type(params.exec_info)}."
                raise TypeError(msg)
            repo = Repo(repo_search_start_path, search_parent_directories=True)

        repo_name = Path(repo.working_dir).name

        return cls(
            name=Path(repo.working_dir).name if name is None else name,
            path=Path(repo.working_dir),
            diff_file=params.run_dir / f"{repo_name}.diff",
            search_parent_directories=False,
            allow_dirty=allow_dirty,
        )

    return build

capsula.GitRepositoryContext.__init__

__init__(
    name: str,
    *,
    path: Path | str,
    diff_file: Path | str | None = None,
    search_parent_directories: bool = False,
    allow_dirty: bool = True
)

PARAMETER	DESCRIPTION
name	TYPE: str
path	TYPE: Path | str
diff_file	TYPE: Path | str | None DEFAULT: None
search_parent_directories	TYPE: bool DEFAULT: False
allow_dirty	TYPE: bool DEFAULT: True

Source code in capsula/_context/_git.py

def __init__(
    self,
    name: str,
    *,
    path: Path | str,
    diff_file: Path | str | None = None,
    search_parent_directories: bool = False,
    allow_dirty: bool = True,
) -> None:
    self._name = name
    self._path = Path(path)
    self._search_parent_directories = search_parent_directories
    self._allow_dirty = allow_dirty
    self._diff_file = None if diff_file is None else Path(diff_file)

Configuration example

Via capsula.toml

[pre-run]
contexts = [
  { type = "GitRepositoryContext", name = "capsula", path = ".", path_relative_to_project_root = true },
]

Via @capsula.context decorator

import capsula

@capsula.run()
@capsula.context(capsula.GitRepositoryContext.builder("capsula"), mode="pre")
def func(): ...

Output example

The following is an example of the output of the GitRepositoryContext, reported by the JsonDumpReporter:

"git": {
  "capsula": {
    "working_dir": "/home/nomura/ghq/github.com/shunichironomura/capsula",
    "sha": "2fa930db2b9c00c467b4627e7d1c7dfb06d41279",
    "remotes": {
      "origin": "ssh://git@github.com/shunichironomura/capsula.git"
    },
    "branch": "improve-docs-index",
    "is_dirty": true,
    "diff_file": "/home/nomura/ghq/github.com/shunichironomura/capsula/vault/20240708_024409_coj0/capsula.diff"
  }
}