Source code for repomatic.git_ops

# Copyright Kevin Deldycke <[email protected]> and contributors.
#
# This program is Free Software; you can redistribute it and/or
# modify it under the terms of the GNU General Public License
# as published by the Free Software Foundation; either version 2
# of the License, or (at your option) any later version.
#
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
# GNU General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with this program; if not, write to the Free Software
# Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.

"""Git operations for GitHub Actions workflows.

This module provides utilities for common Git operations in CI/CD contexts,
with idempotent behavior to allow safe re-runs of failed workflows.

All operations follow a "belt-and-suspenders" approach: combine workflow
timing guarantees (like `workflow_run` ensuring tags exist) with idempotent
guards (like `skip_existing` on tag creation). This ensures correctness
in the face of race conditions, API eventual consistency, and partial failures
that are common in GitHub Actions.

Every git failure raises {class}`GitError`, which carries git's own error
output. A function returns `None` or `False` instead only when it is a probe,
whose question a failure answers.

```{warning} Tag push requires `REPOMATIC_PAT`

Tags pushed with the default `GITHUB_TOKEN` do not trigger downstream
`on.push.tags` workflows. The custom PAT is required so that tagging
a release commit actually fires the publish and release creation jobs.
```
"""

from __future__ import annotations

import logging
import subprocess
from pathlib import Path
from typing import NamedTuple

from packaging.version import Version

from .github.urls import parse_github_repo
from .release import protocol
from .versions import parse_tag_version

TYPE_CHECKING = False
if TYPE_CHECKING:
    from collections.abc import Sequence

COMMIT_IDENTITY_EMAIL = "41898282+github-actions[bot]@users.noreply.github.com"
"""Commit author email for automated commits: GitHub's own Actions bot user.

The `41898282+` prefix is the bot's stable user ID, which makes GitHub link
the commit to the verified `github-actions[bot]` account.
"""

COMMIT_IDENTITY_NAME = "github-actions[bot]"
"""Commit author name for automated commits."""

_BOT_IDENTITY_ARGS = (
    "-c",
    f"user.name={COMMIT_IDENTITY_NAME}",
    "-c",
    f"user.email={COMMIT_IDENTITY_EMAIL}",
)
"""Per-command `git -c` overrides authoring a commit as the CI bot.

CI checkouts carry no git identity of their own, so every command that writes
a commit object (`commit`, `rebase`) has to supply one. Passed per-command
rather than written to the checkout's config, so nothing persists past the
call."""

SHORT_SHA_LENGTH = 7
"""Default SHA length hard-coded to `7`.

```{caution}

The [default is subject to change](https://stackoverflow.com/a/21015031) and
depends on the size of the repository.
```
"""

NULL_SHA = "0" * 40
"""The null SHA used by Git to represent a non-existent commit.

GitHub sends this value as the `before` SHA of a push that creates a branch or
a tag, since there is no previous commit to compare against.
"""

VERSION_TAG_GLOB = "v[0-9]*.[0-9]*.[0-9]*"
"""Shell glob that selects the release tags in `git tag --list`.

A glob is no PEP 440 filter: `v1.2.3_hotfix` matches it. So every tag it
selects is parsed, and a tag naming no version is skipped.
"""

GIT_LOG_FORMAT = "%H%x00%B"
"""`git log` pretty-format placeholders for a single commit: full SHA, then a
`NUL`, then the raw body.

Paired with `git log -z` (which terminates each commit's output with a `NUL`),
this frames the stream as alternating `(hash, message)` tokens. Commit messages
may contain newlines but never `NUL` bytes, so splitting on `NUL` recovers the
fields unambiguously even for multi-line messages.
"""

LEASE_REJECTION_MARKERS = ("stale info", "but expected")
"""What git prints when a `--force-with-lease` push loses its lease.

The client reports `(stale info)` when it sees the branch moved, and the server
reports `cannot lock ref '…': is at X but expected Y` when the branch moves
during the push itself.
"""


[docs] class GitError(subprocess.CalledProcessError, RuntimeError): """A `git` command that exited with a non-zero status. The message carries what git wrote to its standard error. The message of a plain `CalledProcessError` names only the command and the exit code, which leaves a CI failure with no way to tell a lease rejection from a permission error. Also a `RuntimeError`, like {class}`~repomatic.github.gh.GhCommandError`, so a caller handling any failed external command catches it too. """ def __str__(self) -> str: command = ( self.cmd if isinstance(self.cmd, str) else " ".join(map(str, self.cmd)) ) message = f"{command} exited with status {self.returncode}" detail = (self.stderr or "").strip() return f"{message}:\n{detail}" if detail else f"{message}."
[docs] class LeaseRejected(GitError): """A `--force-with-lease` push refused because the branch moved. Another writer published to the branch after the caller read its tip. {func}`force_push_branch` raises it so a caller can tell this lost race from a permission or a network failure, and handle the race on its own. """
[docs] class Commit(NamedTuple): """A minimal git commit. Only the hash and message are ever consumed downstream, so a full git library object (with diffs, modified-file analysis, and complexity metrics) is unnecessary: the `git` CLI feeds these two fields directly. """ hash: str """The commit's full 40-character SHA-1 hash.""" msg: str """The commit message, stripped of surrounding whitespace."""
def _git(*args: str, check: bool = True) -> subprocess.CompletedProcess[str]: """Run a `git` command and capture its output. Decodes output as UTF-8 so non-ASCII commit metadata (accented author names, emoji in messages) survives on platforms whose default encoding is not UTF-8 (Windows `cp1252`). Nothing is logged here. A failure travels as a {class}`GitError` carrying git's error output, and the caller decides whether it is fatal. :param check: Raise on a non-zero exit. A probe, which reads the exit status itself, passes `False`. :raises GitError: When *check* is set and git exits non-zero. """ process = subprocess.run( ["git", *args], capture_output=True, text=True, encoding="UTF-8", check=False, ) if check and process.returncode: raise GitError( process.returncode, process.args, output=process.stdout, stderr=process.stderr, ) return process def _parse_commit_log(output: str) -> tuple[Commit, ...]: """Parse `NUL`-framed `git log --format=GIT_LOG_FORMAT` output into commits. See {data}`GIT_LOG_FORMAT` for the framing. `git log -z` leaves a trailing empty token after the final commit; a plain `git log` does not. Either way, tokens pair up as `(hash, message)`. """ tokens = output.split("\x00") if tokens and not tokens[-1]: tokens.pop() return tuple( Commit(hash=tokens[i], msg=tokens[i + 1].strip()) for i in range(0, len(tokens) - 1, 2) )
[docs] def get_commit(ref: str = "HEAD") -> Commit: """Return the commit at *ref*. :raises GitError: if *ref* does not resolve to a commit present in the repository. """ result = _git("log", "-1", "-z", f"--format={GIT_LOG_FORMAT}", ref) return _parse_commit_log(result.stdout)[0]
[docs] def list_commits(start: str, end: str) -> tuple[Commit, ...]: """Return the commits in the `start..end` range, oldest first. Follows git range semantics: *start* is excluded, *end* is included. Both endpoints must already share history locally, so a shallow clone goes through {func}`deepen_until_related` first. """ result = _git( "log", "--reverse", "-z", f"--format={GIT_LOG_FORMAT}", f"{start}..{end}" ) return _parse_commit_log(result.stdout)
[docs] def commit_exists(ref: str) -> bool: """Return `True` if *ref* resolves to a commit object present locally.""" return _git("cat-file", "-e", f"{ref}^{{commit}}", check=False).returncode == 0
[docs] def head_sha() -> str: """Return the full SHA of the current `HEAD` commit.""" return _git("rev-parse", "HEAD").stdout.strip()
[docs] def current_branch() -> str | None: """Return the checked-out branch name, or `None` when `HEAD` is detached.""" result = _git("symbolic-ref", "--short", "--quiet", "HEAD", check=False) return result.stdout.strip() or None
[docs] def checkout(ref: str) -> None: """Check out *ref* (a branch name or commit SHA).""" _git("checkout", ref)
[docs] def discard_changes() -> None: """Put the index and the working tree back to `HEAD`. Staged changes go too, a file staged as new included: a commit that failed after its `git add` cannot hand its diff to whatever is committed next. Untracked files stay where they are. """ _git("reset", "--hard", "HEAD")
def _status_paths(output: str) -> tuple[str, ...]: """The sorted paths of `git status --porcelain -z --no-renames` *output*.""" # Each entry is two status letters and a space, then the path. return tuple(sorted({entry[3:] for entry in output.split("\0") if entry}))
[docs] def changed_paths() -> tuple[str, ...]: """Return the tracked paths whose index or working tree differs from `HEAD`. What {func}`discard_changes` would throw away: a staged change and an unstaged one both count, an added or a deleted file included, and a rename counts as its two paths. Untracked files do not, since no reset to `HEAD` touches them. :return: The paths, sorted. Empty on a clean tree. """ output = _git( "status", "--porcelain", "-z", "--untracked-files=no", "--no-renames" ).stdout return _status_paths(output)
[docs] class WorkTreeState(NamedTuple): """The commit and the uncommitted paths of a work tree, read at one moment.""" head: str | None """Full SHA of `HEAD`, or `None` before the first commit.""" uncommitted: tuple[str, ...] """The paths `git status` lists, sorted: staged, unstaged, deleted or untracked, each relative to the top level."""
def _is_top_level(root: Path) -> bool: """Whether *root* is the top level of a git work tree.""" process = _git("-C", str(root), "rev-parse", "--show-toplevel", check=False) if process.returncode: return False return Path(process.stdout.strip()).resolve() == root.resolve()
[docs] def read_work_tree(root: Path) -> WorkTreeState | None: """Read the commit and the uncommitted paths of the work tree at *root*. A probe. Runs with `--no-optional-locks`, so a read beside another git process never stops on its `index.lock`. :param root: The directory to read, not necessarily the current one. :return: `None` when *root* is not the top level of a work tree, where the paths a caller holds relative to *root* would not match the ones git lists. """ if not _is_top_level(root): return None head = _git( "-C", str(root), "rev-parse", "--verify", "--quiet", "HEAD", check=False ).stdout.strip() status = _git( "--no-optional-locks", "-C", str(root), "status", "--porcelain", "-z", "--untracked-files=all", "--no-renames", check=False, ) if status.returncode: return None return WorkTreeState(head or None, _status_paths(status.stdout))
[docs] def git_dir_path(root: Path, name: str) -> Path | None: """The path *name* takes inside the git directory of the work tree at *root*. A probe. Resolved by `git rev-parse --git-path`, so each linked worktree gets a path of its own, and git never tracks the file. :param root: The top level of the work tree. :param name: A path relative to the git directory. :return: `None` when *root* is not the top level of a work tree. """ if not _is_top_level(root): return None process = _git("-C", str(root), "rev-parse", "--git-path", name, check=False) if process.returncode: return None # Relative to *root* in a plain checkout, absolute in a linked worktree. return root / process.stdout.strip()
[docs] def show_file(ref: str, path: str) -> str | None: """Return the content of *path* at *ref*, read from the object store. Neither `HEAD` nor the working tree moves, so the read is safe in any checkout, uncommitted changes included. :param ref: Any tree-ish: a branch, a tag, or a commit SHA. :param path: File path, relative to the current directory. :return: The file content, or `None` when *ref* holds no such file. """ shown = _git("show", f"{ref}:./{path}", check=False) if shown.returncode: logging.debug(f"{ref} holds no {path}: {shown.stderr.strip()}") return None return shown.stdout
[docs] def restore_paths(ref: str, paths: Sequence[str | Path]) -> tuple[str, ...]: """Overwrite *paths* in the working tree with the content they hold at *ref*. `HEAD` stays where it is, so the checkout keeps the source tree and lock file it was cloned with and only the named files travel. That is the whole point over a `git checkout` of the branch: a job reading a file back from an open pull request still runs the code of the branch it was called on. A path *ref* does not carry is skipped rather than deleted. The caller names the files it means to read, and one missing from *ref* is the first-run case, not an instruction to remove anything. :param ref: Any tree-ish: a branch, a tag, or a commit SHA. :param paths: Files to restore, absolute or relative to the current directory. One outside the working tree is skipped. :return: The paths actually restored, as repository-relative pathspecs. """ root = Path(_git("rev-parse", "--show-toplevel").stdout.strip()).resolve() restorable = [] for path in paths: try: pathspec = Path(path).resolve().relative_to(root).as_posix() except ValueError: logging.debug(f"{path} sits outside {root}, not restoring it.") continue if _git("cat-file", "-e", f"{ref}:{pathspec}", check=False).returncode: logging.debug(f"{ref} carries no {pathspec}, not restoring it.") continue restorable.append(pathspec) if restorable: _git("checkout", ref, "--", *restorable) return tuple(restorable)
[docs] def is_shallow() -> bool: """Return `True` when the repository is a shallow clone.""" return _git("rev-parse", "--is-shallow-repository").stdout.strip() == "true"
[docs] def fetch_commit(sha: str, remote: str = "origin") -> bool: """Make the commit *sha* present locally, fetching it when it is absent. A shallow clone fetches the commit alone (`--depth=1`): its tree is all a comparison needs, and the history behind it can be large. A complete clone fetches without a depth, so it stays complete. :param sha: Full SHA of the commit. :param remote: Remote to fetch from. :return: `True` when the commit is present afterwards. `False` when the remote does not serve it, like a commit a force-push left unreachable. """ if commit_exists(sha): return True depth = ("--depth=1",) if is_shallow() else () fetched = _git("fetch", *depth, "--no-tags", remote, sha, check=False) if fetched.returncode: logging.debug(f"{remote} does not serve {sha}: {fetched.stderr.strip()}") return False return True
[docs] def diff_names(start: str, end: str) -> tuple[str, ...]: """Return the paths that differ between *start* and *end*. :raises GitError: if either ref is unknown. """ output = _git("diff", "--name-only", start, end).stdout.strip() return tuple(output.splitlines()) if output else ()
[docs] def tree_sha(ref: str = "HEAD") -> str: """Return the SHA of the tree *ref* points at. Two commits sharing a tree SHA carry byte-identical content, whatever their message, author or parent. That makes this the cheapest way to ask whether re-running a generator produced anything new. """ return _git("rev-parse", f"{ref}^{{tree}}").stdout.strip()
[docs] def count_commits_between(start: str, end: str) -> int: """Return the number of commits in the `start..end` range. Follows git range semantics: *start* is excluded, *end* is included. """ return int(_git("rev-list", "--count", f"{start}..{end}").stdout.strip())
[docs] def is_ancestor(maybe_ancestor: str, ref: str) -> bool | None: """Return whether *maybe_ancestor* is reachable from *ref*. :return: `True` or `False` when git can relate the two commits, and `None` when it cannot: a shallow clone whose grafted history stops before their common ancestor answers neither yes nor no. """ related = _git("merge-base", "--is-ancestor", maybe_ancestor, ref, check=False) if related.returncode in (0, 1): return related.returncode == 0 logging.debug(f"Cannot relate {maybe_ancestor} to {ref}: {related.stderr.strip()}") return None
[docs] def merge_base(left: str, right: str) -> str | None: """Return the best common ancestor of two commits, or `None` if unrelated. `None` also covers the shallow-clone case described in {func}`is_ancestor`, and a commit absent from the clone. """ common = _git("merge-base", left, right, check=False) return common.stdout.strip() if common.returncode == 0 else None
[docs] def rebase_onto(new_base: str, old_base: str, branch: str) -> bool: """Replay `old_base..branch` on top of *new_base*, keeping the replayed side. `--strategy-option=theirs` resolves overlaps in favour of the commits being replayed, which for a generated branch means the freshly generated content wins over whatever the new base happens to carry. :return: `True` on success. On conflict the rebase is aborted and `False` returned, leaving *branch* exactly as it was: a branch built on a slightly stale base still opens a usable pull request, and the next run converges it, so this is not worth failing the job over. """ rebased = _git( *_BOT_IDENTITY_ARGS, "rebase", "--onto", new_base, old_base, branch, "--strategy-option=theirs", check=False, ) if rebased.returncode: _git("rebase", "--abort", check=False) logging.warning( f"Could not replay {branch} onto {new_base}: {rebased.stderr.strip()}\n" "Publishing it on its original base instead." ) return False return True
[docs] def create_branch(name: str) -> None: """Create or reset branch *name* at `HEAD` and switch to it. The index and working tree carry over untouched, so staged changes made before the call survive into a commit made after it. """ _git("checkout", "-B", name)
[docs] def delete_branch(name: str) -> None: """Delete the local branch *name*, even when unmerged. Tolerates a branch that is not there. Callers reach this from a `finally` that cleans up a scratch branch, where the failure being cleaned up after may be the very thing that stopped the branch from being created: raising here would replace the real error with a confusing one. """ deleted = _git("branch", "--delete", "--force", name, check=False) if deleted.returncode: logging.debug(f"Could not delete local branch {name}: {deleted.stderr.strip()}")
[docs] def stage_all(paths: Sequence[str] = ()) -> bool: """Stage working-tree changes, untracked files included. Stages the whole tree by default. *paths* narrows that to a git pathspec list, for a job whose own steps leave more behind than they mean to commit: a linter installed into the checkout, a lock file a package manager rewrote on the way past. Anything outside the pathspec stays dirty and is left for the caller to restore or discard. A pathspec matching nothing is dropped rather than fatal. `git add` exits 128 on the first one it cannot resolve and stages nothing at all, so a glob covering output a run happened not to produce would take the whole job down with it. Filtering first also keeps one stale entry in a list from silently costing the others their staging. :param paths: Git pathspecs to stage. Empty stages everything. :return: `True` when the index ends up carrying something to commit. """ if paths: matching = [path for path in paths if _pathspec_matches(path)] if matching: _git("add", "--all", "--", *matching) else: _git("add", "--all") return _git("diff", "--cached", "--quiet", check=False).returncode != 0
def _pathspec_matches(pathspec: str) -> bool: """Whether *pathspec* resolves to any tracked or untracked file. Both halves are needed: `--cached` covers a tracked file the run modified or deleted, `--others` an output file it created. A pathspec matching only ignored files reports `False`, which is the honest answer, since staging it would have added nothing either. """ listed = _git( "ls-files", "--cached", "--others", "--exclude-standard", "--", pathspec ) return bool(listed.stdout.strip())
[docs] def commit_staged(message: str) -> str: """Commit the staged tree as the CI bot and return the new commit SHA. The identity is supplied per-command via `-c`, since CI checkouts carry no git identity of their own. """ _git(*_BOT_IDENTITY_ARGS, "commit", "--message", message) return head_sha()
[docs] def commit_tracked(message: str) -> str: """Commit every change to a tracked file as the CI bot. Stages what `git commit --all` takes: modified and deleted tracked files. An untracked file stays out of the commit, so nothing a tool leaves behind in the checkout can ride along. :param message: The commit message. :return: The SHA of the new commit. :raises GitError: When no tracked file changed, or when git cannot commit. """ _git("add", "--update") return commit_staged(message)
[docs] def fetch_remote_branch(branch: str, remote: str = "origin") -> str | None: """Fetch *branch* into its remote-tracking ref and return the SHA. The refspec is explicit because `actions/checkout` configures a single-branch fetch refspec, under which a bare ``git fetch origin {branch}`` updates `FETCH_HEAD` but leaves ``refs/remotes/{remote}/{branch}`` absent. Writing the remote-tracking ref is what later lets a push take a `--force-with-lease` on it. :return: The remote branch tip, or `None` when the branch does not exist on the remote. """ fetched = _git( "fetch", "--force", remote, f"refs/heads/{branch}:refs/remotes/{remote}/{branch}", check=False, ) if fetched.returncode: logging.debug(f"No {branch!r} branch on {remote}: {fetched.stderr.strip()}") return None return _git("rev-parse", f"refs/remotes/{remote}/{branch}").stdout.strip()
[docs] def force_push_branch( local_ref: str, branch: str, expected_sha: str | None, remote: str = "origin", ) -> None: """Publish *local_ref* as *branch* on *remote*, overwriting what is there. *expected_sha* is the remote tip the caller last observed, which becomes a `--force-with-lease` guard: the push is refused when the branch moved in between, rather than silently discarding the other writer's commit. Pass `None` to create a branch that does not exist yet, where a plain push already fails if someone wins the race. :raises LeaseRejected: When the branch moved since *expected_sha* was read. :raises GitError: When the push is rejected for any other reason. """ args = ["push"] if expected_sha: args.append(f"--force-with-lease={branch}:{expected_sha}") args.extend([remote, f"{local_ref}:refs/heads/{branch}"]) try: _git(*args) except GitError as error: if expected_sha and any( marker in (error.stderr or "") for marker in LEASE_REJECTION_MARKERS ): raise LeaseRejected( error.returncode, error.cmd, output=error.output, stderr=error.stderr ) from error raise logging.info(f"Pushed {local_ref} to {remote}/{branch}.")
[docs] def delete_remote_branch(branch: str, remote: str = "origin") -> None: """Delete *branch* from *remote*, tolerating a branch already gone.""" deleted = _git("push", "--delete", remote, f"refs/heads/{branch}", check=False) if deleted.returncode: logging.warning(f"Could not delete {remote}/{branch}: {deleted.stderr.strip()}") return logging.info(f"Deleted {remote}/{branch}.")
[docs] def list_contributor_identities() -> set[str]: """Return every author and committer identity found in the history. No normalization happens: all variations of author and committer strings attached to all commits are returned as-is, in `Name <email>` form. For format output syntax, see: https://git-scm.com/docs/pretty-formats#Documentation/pretty-formats.txt-aN :raises GitError: When git cannot read the history. """ process = _git("log", "--pretty=format:%aN <%aE>%n%cN <%cE>") return {line for line in map(str.strip, process.stdout.splitlines()) if line}
[docs] def get_repo_slug_from_remote(remote: str = "origin") -> str | None: """Extract the `owner/repo` slug from a git remote URL. Reads both HTTPS and SSH GitHub remotes, through {func}`~repomatic.github.urls.parse_github_repo`. Returns `None` if the remote is not set, not a GitHub URL, or git is unavailable. """ try: result = _git("remote", "get-url", remote, check=False) except FileNotFoundError: return None if result.returncode: return None parsed = parse_github_repo(result.stdout.strip()) return "/".join(parsed) if parsed else None
def _version_tags() -> dict[str, tuple[Version, str]]: """List the release tags, with the version each names and its date. The one `git tag` call behind {func}`get_latest_tag_version` and {func}`get_all_version_tags`. A tag {data}`VERSION_TAG_GLOB` selects but that names no PEP 440 version is skipped: one odd tag must not break every reader of the others. :return: `(version, date)` pairs keyed by tag name, the date in `YYYY-MM-DD` format. :raises GitError: When git cannot list the tags. """ output = _git( "tag", "--list", VERSION_TAG_GLOB, "--format=%(refname:short) %(creatordate:short)", ).stdout tags = {} for line in output.splitlines(): tag, _, date = line.partition(" ") version = parse_tag_version(tag) if version is None: logging.debug(f"Skipping non-PEP 440 tag: {tag}") continue tags[tag] = (version, date) return tags
[docs] def get_latest_tag_version() -> Version | None: """Return the highest release version among the `vX.Y.Z` tags. :return: The version, or `None` when no tag names one. :raises GitError: When git cannot list the tags. """ versions = [version for version, _date in _version_tags().values()] if not versions: logging.debug("No version tags found in repository.") return None latest = max(versions) logging.debug(f"Latest tag version: {latest}") return latest
[docs] def get_release_version_from_commits(max_count: int = 10) -> Version | None: """Extract release version from recent commit messages. Searches recent commits for messages matching the pattern `[changelog] Release vX.Y.Z` and returns the version from the most recent match. This provides a fallback when tags haven't been pushed yet due to race conditions between workflows. The release commit message contains the version information before the tag is created. :param max_count: Maximum number of commits to search. :return: The version from the most recent release commit, or `None` if not found. """ result = _git( "log", "-n", str(max_count), "-z", f"--format={GIT_LOG_FORMAT}", "HEAD" ) for commit in _parse_commit_log(result.stdout): match = protocol.RELEASE_COMMIT_PATTERN.fullmatch(commit.msg) if match: version = Version(match.group("version")) logging.debug(f"Found release version {version} in commit {commit.hash}") return version logging.debug("No release commit found in recent history.") return None
[docs] def get_all_version_tags() -> dict[str, str]: """Map every release version to the date of its tag. :return: Version strings (without the `v` prefix) mapped to dates in `YYYY-MM-DD` format. :raises GitError: When git cannot list the tags. """ return { tag.removeprefix("v"): date for tag, (_version, date) in _version_tags().items() }
[docs] def create_and_push_tag( tag: str, commit: str | None = None, push: bool = True, skip_existing: bool = True, ) -> bool: """Create and optionally push a Git tag. This function is idempotent: if the tag already exists and `skip_existing` is True, it returns False without failing. This allows safe re-runs of workflows that were interrupted after tag creation but before other steps. :param tag: The tag name to create. :param commit: The commit to tag. Defaults to HEAD. :param push: Whether to push the tag to the `origin` remote. :param skip_existing: If True, skip silently when tag exists. If False, raise an error. Defaults to True. :return: True if the tag was created, False if it already existed. :raises ValueError: If tag exists and skip_existing is False. :raises GitError: If Git operations fail. """ ref = f"refs/tags/{tag}" if _git("show-ref", "--verify", "--quiet", ref, check=False).returncode == 0: if skip_existing: logging.info(f"Tag {tag!r} already exists, skipping.") return False msg = f"Tag {tag!r} already exists." raise ValueError(msg) _git("tag", tag, *((commit,) if commit else ())) logging.info(f"Created tag {tag!r}") if push: _git("push", "origin", ref) logging.info(f"Pushed tag {tag!r} to remote.") return True