git_well.git_archive_source module

Archive committed source with full Git history and initialized submodules.

class git_well.git_archive_source.SubmoduleStatus(status: str, sha: str, path: str, line: str)

Bases: object

Parsed information from git submodule status --recursive.

status: str

sha: str

path: str

line: str

class git_well.git_archive_source.ArchiveSourceCLI(*args: Any, **kwargs: Any)

Bases: DataConfig

Archive committed source with full Git history and initialized submodules.

This is related to, but intentionally broader than, git archive. Plain git archive is excellent for producing a source-only tar or zip snapshot of one repository tree, but it does not include .git metadata and it does not recursively materialize submodule contents by itself. By default this command stages clean committed checkouts of the superproject plus each initialized recursive submodule so the resulting archive can include real .git directories and git log remains available after unpacking. Use --depth 0 to request source-only behavior, where this command delegates tree export to git archive and omits .git metadata.

Local edits, untracked files, ignored files, and build outputs are excluded in all modes. Submodules must already be initialized locally.

Valid options: []

Parameters:

• *args – positional arguments for this data config

• **kwargs – keyword arguments for this data config

classmethod main(argv: list[str] | str | bool | None = True, **kwargs: Any) → Path

default = {'depth': <Value('full')>, 'format': <Value('auto')>, 'output': <Value(None)>, 'repo_dpath': <Value('.')>, 'verbose': <Value(1)>}

git_well.git_archive_source.main(argv: list[str] | str | bool | None = True, **kwargs: Any) → Path

Command line entry point for ArchiveSourceCLI.

git_well.git_archive_source.archive_source(repo_dpath: str | PathLike = '.', output: str | PathLike | None = None, depth: str | int | None = 'full', format: Literal['auto', 'tar', 'tar.gz', 'tgz', 'zip', 'tar.bz2', 'tbz2', 'tar.xz', 'txz'] = 'auto', verbose: int = 1) → Path

Create an archive of committed source in a Git repository.

Parameters:

• repo_dpath – Repository to archive. The repository containing this path is used.

• output – Exact archive path to write. Relative paths are interpreted relative to the repository root. If unspecified, the archive is written to the repository root as <repo>-source-<timestamp>-<short sha>.<format-extension>.

• depth – 'full' or None includes full current-HEAD history. A positive integer creates shallow staged checkouts. 0 omits Git metadata and uses source-only git archive exports.

• format – Archive format. 'auto' infers from the output extension when possible and otherwise defaults to 'tar.gz'.

• verbose – Verbosity level.

Returns:

The generated archive path.

Notes

This function only archives committed/tracked source. Local edits, untracked files, ignored files, and build outputs are deliberately excluded.

git_well.git_archive_source.build_source_archive(*args: Any, **kwargs: Any) → Path

Backwards-compatible Python alias for archive_source().

git_well.git_archive_source._coerce_repo(repo_dpath: PathLike) → git.Repo

git_well.git_archive_source._assert_has_head(repo: git.Repo) → None

git_well.git_archive_source._normalize_depth(depth: str | int | None) → int | None

git_well.git_archive_source._normalize_format(format: str) → Literal['tar', 'tar.gz', 'zip', 'tar.bz2', 'tar.xz']

git_well.git_archive_source._infer_format_from_output(output: str | PathLike) → Literal['tar', 'tar.gz', 'zip', 'tar.bz2', 'tar.xz']

git_well.git_archive_source._resolve_archive_format(output: str | PathLike | None, format: Literal['auto', 'tar', 'tar.gz', 'tgz', 'zip', 'tar.bz2', 'tbz2', 'tar.xz', 'txz']) → Literal['tar', 'tar.gz', 'zip', 'tar.bz2', 'tar.xz']

git_well.git_archive_source._resolve_output(repo_root: Path, output: str | PathLike | None, prefix: str, archive_format: Literal['tar', 'tar.gz', 'zip', 'tar.bz2', 'tar.xz']) → Path

git_well.git_archive_source._submodule_status(repo: git.Repo) → List[SubmoduleStatus]

git_well.git_archive_source._clone_options_for_depth(clone_depth: int | None) → List[str]

git_well.git_archive_source._clone_committed_checkout(src: git.Repo, dst: PathLike, commit: str, label: str, clone_depth: int | None, log: _Logger) → None

git_well.git_archive_source._checkout_commit(repo: git.Repo, commit: str, label: str, clone_depth: int | None, log: _Logger) → None

git_well.git_archive_source._extract_git_archive(repo: git.Repo, treeish: str, dst: Path, prefix: str) → None

git_well.git_archive_source._safe_extractall(tar: tarfile.TarFile, dst: Path) → None

git_well.git_archive_source._append_manifest_exclude(repo_dpath: str | PathLike) → None

git_well.git_archive_source._write_manifest(manifest: Path, repo: git.Repo, repo_root: Path, repo_name: str, prefix: str, timestamp: str, head_sha: str, short_sha: str, include_git_history: bool, clone_depth: int | None, submodule_status: List[SubmoduleStatus]) → None

git_well.git_archive_source._write_archive(stage: Path, prefix: str, archive_path: Path, archive_format: Literal['tar', 'tar.gz', 'zip', 'tar.bz2', 'tar.xz']) → None

git_well.git_archive_source._add_zip_entry(zfile: zipfile.ZipFile, path: Path, arcname: Path) → None

class git_well.git_archive_source._Logger(verbose: int)

Bases: object

__call__(msg: str) → None