ftag.git_check#

Small utilities for interacting with a local Git repository.

This module provides helper functions to:

  • detect whether a given path is inside a Git working tree,

  • fail fast when there are uncommitted changes,

  • verify that a local clone is a fork of an expected upstream,

  • create and push an annotated tag, and

  • read the current short commit hash.

All functions run Git commands via subprocess. If Git is not installed or the command cannot be executed, the underlying OS error (e.g. OSError) will propagate.

Exceptions#

GitError

Raised when a Git-related precondition is not satisfied.

Functions#

is_git_repo(→ bool)

Return whether path is inside a Git working tree.

check_for_uncommitted_changes(→ None)

Raise if the repository at path has uncommitted changes.

check_for_fork(→ None)

Ensure the local clone's origin remote is a fork of upstream.

create_and_push_tag(→ None)

Create an annotated Git tag and push it to origin.

get_git_hash(→ str | None)

Return the short commit hash for HEAD at path, if available.

Module Contents#

exception ftag.git_check.GitError#

Bases: Exception

Raised when a Git-related precondition is not satisfied.

Initialize self. See help(type(self)) for accurate signature.

ftag.git_check.is_git_repo(path: str | os.PathLike[str]) → bool#

Return whether path is inside a Git working tree.

Parameters:

path (str | PathLike[str]) – Filesystem path used as the current working directory for the Git command.

Returns:

True if path is inside a Git working tree, False otherwise.

Return type:

bool

Notes

This function runs:

git rev-parse --is-inside-work-tree HEAD

Any non-zero exit status is treated as “not a Git repository”. If Git is not available on the system, an OSError may be raised by subprocess.

ftag.git_check.check_for_uncommitted_changes(path: str | os.PathLike[str]) → None#

Raise if the repository at path has uncommitted changes.

Parameters:

path (str | PathLike[str]) – Filesystem path to the repository root or any directory within it.

Raises:

GitError – If path is a Git repository and there are uncommitted changes.

Notes

  • If path is not a Git repository, the function returns silently.

  • If the current process is running under pytest (detected via sys.modules), the check is skipped and the function returns.

ftag.git_check.check_for_fork(path: str | os.PathLike[str], upstream: str) → None#

Ensure the local clone’s origin remote is a fork of upstream.

Parameters:

  • path (str | PathLike[str]) – Filesystem path to the repository root or any directory within it.

  • upstream (str) – Expected upstream repository URL substring (e.g. 'github.com/org/repo').

Raises:

GitError – If the repository is present but its origin URL does not contain upstream.

Notes

If path is not a Git repository, the function returns silently.

ftag.git_check.create_and_push_tag(path: str | os.PathLike[str], upstream: str, tagname: str, msg: str) → None#

Create an annotated Git tag and push it to origin.

Parameters:

  • path (str | PathLike[str]) – Filesystem path to the repository root or any directory within it.

  • upstream (str) – Expected upstream repository URL substring; passed to check_for_fork().

  • tagname (str) – Name of the tag to create.

  • msg (str) – Annotation message for the tag (git tag -m).

Notes

If path is not a Git repository, the function returns silently.

ftag.git_check.get_git_hash(path: str | os.PathLike[str]) → str | None#

Return the short commit hash for HEAD at path, if available.

Parameters:

path (str | PathLike[str]) – Filesystem path to the repository root or any directory within it.

Returns:

The short (--short) commit hash as a string, or None if path is not a Git repository.

Return type:

str | None