Git And Hashing Helpers

Module: thornforge.buildsite.git

Overview

This module wraps Git subprocess calls, exports tagged refs, clones remote repositories, copies local worktrees, and computes the content digests used to deduplicate documentation builds.

Autodoc

Git and hashing helpers used to materialize and deduplicate docs builds.

These helpers isolate direct Git process calls and the content hashing logic used to decide whether multiple versions can reuse the same canonical build.

thornforge.buildsite.git.clone_repository(source_url: str, destination: Path) → None

Clone a remote repository to a local directory.

Parameters:

• source_url – Remote Git URL to clone.

• destination – Local directory path that should receive the clone.

Side Effects:

Spawns git clone and writes repository contents to destination.

Returns:

None.

thornforge.buildsite.git.copy_worktree(source_root: Path, destination: Path) → None

Copy a local repository tree while excluding transient directories.

Parameters:

• source_root – Existing local repository directory to copy from.

• destination – Destination directory that should receive the copied tree.

Side Effects:

Copies the repository contents to destination while skipping VCS and common cache directories that should not influence docs builds.

Returns:

None.

thornforge.buildsite.git.extract_ref(repo_root: Path, ref: str, destination: Path) → None

Export a Git ref into a plain directory tree.

Parameters:

• repo_root – Git repository root used as the source for git archive.

• ref – Git reference to export, such as a tag or branch name.

• destination – Directory that should receive the extracted archive.

Side Effects:

Creates destination if needed and writes the archived repository contents into it without any Git metadata.

Returns:

None. Files are extracted to disk.

thornforge.buildsite.git.hash_version_inputs(repo_root: Path, tag: str, input_paths: tuple[str, ...]) → str

Build a stable cache key for a tagged repository version.

Parameters:

• repo_root – Git repository root from which tree objects are read.

• tag – Git reference naming the version to hash.

• input_paths – Repository-relative paths that should contribute to the build key, typically docs sources and metadata files.

Returns:

A short hexadecimal digest string used as the canonical build directory name for this version.

Notes

The hash includes both repository content and ThornForge-owned assets so rebuilt output changes when the shared UI assets change.

thornforge.buildsite.git.hash_worktree_inputs(repo_root: Path, input_paths: tuple[str, ...]) → str

Build a cache key for a non-tagged local working tree.

Parameters:

• repo_root – Local repository directory whose on-disk files should be hashed.

• input_paths – Repository-relative paths that should participate in the digest.

Returns:

A short hexadecimal digest string used as the canonical build directory name for the current checkout.

thornforge.buildsite.git.is_git_repository(repo_root: Path) → bool

Return whether repo_root behaves like a usable Git repository.

Parameters:

repo_root – Candidate repository root to probe.

Returns:

True when git rev-parse --show-toplevel succeeds in that directory, otherwise False.

thornforge.buildsite.git.run_git(repo_root: Path, *args: str) → str

Run a Git command that is expected to return text.

Parameters:

• repo_root – Repository root used as the subprocess working directory.

• *args – Positional arguments passed after the git executable.

Returns:

Standard output from the Git subprocess with surrounding whitespace stripped.

Raises:

subprocess.CalledProcessError – If the Git command exits with a non-zero status.

thornforge.buildsite.git.run_git_binary(repo_root: Path, *args: str) → bytes

Run a Git command that should return binary-safe output.

Parameters:

• repo_root – Repository root used as the subprocess working directory.

• *args – Positional arguments passed after the git executable.

Returns:

Raw bytes from standard output. This is used for tree inspection and hashing workflows where text decoding would be lossy.

thornforge.buildsite.git.shutil_copytree(source_root: Path, destination: Path, ignore) → None

Call shutil.copytree through a small local wrapper.

Parameters:

• source_root – Source directory to copy.

• destination – Destination directory to create or merge into.

• ignore – Ignore callback forwarded to shutil.copytree.

Returns:

None. Files are copied to disk.

thornforge.buildsite.git.update_asset_digest(digest: hashlib._Hash) → None

Mix ThornForge-owned asset files into an existing digest object.

Parameters:

digest – Mutable hash object that already contains repository-specific content.

Side Effects:

Reads shared CSS, JavaScript, and template asset files and appends their paths and contents into digest.

Returns:

None. The supplied digest object is updated in place.