Git

git

Subprocess-based git helpers for managing external repository checkouts.

Functions:

Name	Description
clone	Shallow-clone a git repository to a local destination.
repo_info	Return a short commit summary for a git repo, or an empty string.
update_at_date	Fetch history back to date and checkout the last commit before it.
update_latest	Fetch and reset to the tip of the remote branch (shallow).

clone

clone(url: str, dest: Path, branch: str) -> None

Shallow-clone a git repository to a local destination.

Parameters:

Name	Type	Description	Default
url	str	Remote URL to clone from.	required
dest	Path	Local path where the repository will be created.	required
branch	str	Branch name to check out.	required

Source code in src/oops/utils/git.py

def clone(url: str, dest: Path, branch: str) -> None:
    """Shallow-clone a git repository to a local destination.

    Args:
        url: Remote URL to clone from.
        dest: Local path where the repository will be created.
        branch: Branch name to check out.
    """
    _git(
        "clone",
        url,
        "--branch",
        branch,
        "--depth",
        "1",
        "--single-branch",
        str(dest),
    )

repo_info

repo_info(path: Path) -> str

Return a short commit summary for a git repo, or an empty string.

Parameters:

Name	Type	Description	Default
path	Path	Path to a local git repository.	required

Returns:

Type	Description
str	String of the form <hash> <date> or empty string if unavailable.

Source code in src/oops/utils/git.py

def repo_info(path: Path) -> str:
    """Return a short commit summary for a git repo, or an empty string.

    Args:
        path: Path to a local git repository.

    Returns:
        String of the form ``<hash>  <date>`` or empty string if unavailable.
    """
    if not path.exists():
        return ""
    try:
        return _git_output("log", "-1", "--format=%h  %ai", cwd=path) or ""
    except subprocess.CalledProcessError:
        return ""

update_at_date

update_at_date(dest: Path, date: str) -> None

Fetch history back to date and checkout the last commit before it.

The result is a detached HEAD pointing at the latest commit whose author date is ≤ DATE 23:59:59.

Parameters:

Name	Type	Description	Default
dest	Path	Local repository path to update.	required
date	str	Target date in YYYY-MM-DD format.	required

Raises:

Type	Description
ClickException	If no commit is found at or before date.

Source code in src/oops/utils/git.py

def update_at_date(dest: Path, date: str) -> None:
    """Fetch history back to *date* and checkout the last commit before it.

    The result is a detached HEAD pointing at the latest commit whose author
    date is ≤ DATE 23:59:59.

    Args:
        dest: Local repository path to update.
        date: Target date in YYYY-MM-DD format.

    Raises:
        click.ClickException: If no commit is found at or before *date*.
    """
    _git("fetch", "--shallow-since", date, cwd=dest)

    commit = _git_output(
        "rev-list",
        "-1",
        f"--before={date} 23:59:59",
        "FETCH_HEAD",
        cwd=dest,
    )

    if not commit:
        raise click.ClickException(
            f"No commit found at or before {date} in '{dest}'. "
            "Try an earlier date or check that the branch has history that far back."
        )

    click.echo(f"  Checking out {commit[:12]}  (last commit ≤ {date})")
    _git("checkout", commit, cwd=dest)

update_latest

update_latest(dest: Path) -> None

Fetch and reset to the tip of the remote branch (shallow).

Parameters:

Name	Type	Description	Default
dest	Path	Local repository path to update.	required

Source code in src/oops/utils/git.py

def update_latest(dest: Path) -> None:
    """Fetch and reset to the tip of the remote branch (shallow).

    Args:
        dest: Local repository path to update.
    """
    _git("fetch", "--depth", "1", cwd=dest)
    _git("reset", "--hard", "FETCH_HEAD", cwd=dest)