mafw.devtools.git

Git operations for MAFw development tools.

This module centralizes all functions that shell out to git commands, used by the release workflow, documentation builder, and dependency management.

Module Attributes

PYPROJECT_FILE	Path to the TOML file containing the project dependencies.
STABLE_TAG_PATTERN	Regular expression used to identify stable git tags in the form vX.Y.Z.

Functions

check_main_branch()	Ensure the release process is executed from the main branch.
commit_changes(version, dry_run, *[, ...])	Commit tracked release artifacts for the target version.
commit_dependency_unfreeze(dry_run)	Commit the unfreezing of dependency upper bounds to main.
create_tag(version, dry_run)	Create the local git tag for the target version.
ensure_clean_git()	Ensure the git working tree is clean (excluding untracked files).
get_current_branch()	Get the name of the currently checked out branch.
get_git_tags([min_version])	Return list of (Version, tag) tuples sorted ascending.
get_last_stable_tag()	Return the latest stable tag matching vX.Y.Z.
git_rev_of(ref)	Get the git revision hash for a given reference.
is_ancestor(a, b)	Return True if commit a is ancestor of commit b (git merge-base --is-ancestor).
prevent_duplicate_tag(version)	Ensure the target release tag does not already exist.
push_changes(dry_run)	Push commits and tags to the remote repository.
sort_tags_semver(tags)	Sort tags using semantic versioning comparison.

mafw.devtools.git.check_main_branch() → None

Ensure the release process is executed from the main branch.

Raises:

DevtoolsError – If the current branch is not main.

mafw.devtools.git.commit_changes(version: str, dry_run: bool, *, include_changelog: bool = True) → None

Commit tracked release artifacts for the target version.

Parameters:

• version (str) – Target release version.

• dry_run (bool) – Whether command execution is disabled.

• include_changelog (bool) – Whether CHANGELOG.md should be staged and committed as part of the release artifacts.

mafw.devtools.git.commit_dependency_unfreeze(dry_run: bool) → None

Commit the unfreezing of dependency upper bounds to main.

Parameters:

dry_run (bool) – Whether command execution is disabled.

mafw.devtools.git.create_tag(version: str, dry_run: bool) → str

Create the local git tag for the target version.

Parameters:

• version (str) – Target release version.

• dry_run (bool) – Whether command execution is disabled.

Returns:

Created tag name.

Return type:

str

mafw.devtools.git.ensure_clean_git() → None

Ensure the git working tree is clean (excluding untracked files).

Raises:

DevtoolsError – If tracked changes are present.

mafw.devtools.git.get_current_branch() → str

Get the name of the currently checked out branch.

Returns:

Name of the current branch

Return type:

str

mafw.devtools.git.get_git_tags(min_version: str | None = None) → list[tuple[Version, Any]]

Return list of (Version, tag) tuples sorted ascending.

Parameters:

min_version (str | None) – Minimum version to consider, defaults to None

Returns:

List of (Version, tag) tuples

Return type:

list[tuple[Version, Any]]

mafw.devtools.git.get_last_stable_tag() → str | None

Return the latest stable tag matching vX.Y.Z.

Returns:

Latest stable tag or None when no stable tags are present.

Return type:

str | None

mafw.devtools.git.git_rev_of(ref: str) → str

Get the git revision hash for a given reference.

Parameters:

ref (str) – Git reference (tag, branch, commit hash)

Returns:

Git revision hash

Return type:

str

Raises:

RuntimeError – If git rev-list fails

mafw.devtools.git.is_ancestor(a: str, b: str) → bool

Return True if commit a is ancestor of commit b (git merge-base –is-ancestor).

Parameters:

• a (str) – First commit reference

• b (str) – Second commit reference

Returns:

True if a is ancestor of b

Return type:

bool

mafw.devtools.git.prevent_duplicate_tag(version: str) → None

Ensure the target release tag does not already exist.

Parameters:

version (str) – Target release version.

Raises:

DevtoolsError – If v<version> already exists.

mafw.devtools.git.push_changes(dry_run: bool) → None

Push commits and tags to the remote repository.

Parameters:

dry_run (bool) – Whether command execution is disabled.

mafw.devtools.git.sort_tags_semver(tags: list[str]) → list[str]

Sort tags using semantic versioning comparison.

Parameters:

tags (list[str]) – List of tag strings to sort

Returns:

Sorted list of tag strings

Return type:

list[str]

mafw.devtools.git.PYPROJECT_FILE = PosixPath('pyproject.toml')

Path to the TOML file containing the project dependencies.

mafw.devtools.git.STABLE_TAG_PATTERN = re.compile('^v(?P<major>\\d+)\\.(?P<minor>\\d+)\\.(?P<micro>\\d+)$')

Regular expression used to identify stable git tags in the form vX.Y.Z.