stouputils.continuous_delivery.git module#

This module contains utilities for generating changelogs from local git repositories.

changelog_cli: CLI interface for generating changelogs from local git history
get_commits_since_tag: Get all commits since a specific tag
get_commits_since_date: Get all commits since a specific date
get_commits_since_commit: Get all commits since a specific commit
parse_remote_url: Parse a git remote URL to extract the base URL for commit links

Usage: - stouputils changelog [tag|date|commit] [value] [–remote <remote>] [-o <file>]

stouputils changelog # Uses latest tag (default)
stouputils changelog tag v1.9.0 # All commits since tag v1.9.0
stouputils changelog date 2026/01/05 # All commits since date
stouputils changelog commit 847b27e # All commits since commit
stouputils changelog –remote origin # Use origin remote for commit URLs
stouputils changelog -o CHANGELOG.md # Output to file

run_git_command( args: list[str], cwd: str | None = None, ) → str[source]#

Run a git command and return the output.

Parameters:

args – Git command arguments (without ‘git’ prefix)
cwd – Working directory for the command

Returns:

Command output (stdout)

Raises:

RuntimeError – If the git command fails

get_local_tags( cwd: str | None = None, ) → list[tuple[str, str]][source]#

Get all tags from the local git repository, sorted by version.

Parameters:: cwd – Working directory for the git command
Returns:: List of (tag_name, commit_sha) tuples, sorted by version (newest first)

get_latest_tag( cwd: str | None = None, exclude_version: str | None = None, ) → tuple[str, str] | tuple[None, None][source]#

Get the latest tag from the local git repository.

Parameters:

cwd – Working directory for the git command
exclude_version – Version to exclude from the search

Returns:

(tag_name, commit_sha) or (None, None) if no tags exist

get_commits_since_tag( tag: str, cwd: str | None = None, ) → list[tuple[str, str]][source]#

Get all commits since a specific tag.

Parameters:

tag – Tag name to start from (exclusive)
cwd – Working directory for the git command

Returns:

List of (sha, message) tuples

get_commits_since_date( date_str: str, cwd: str | None = None, ) → list[tuple[str, str]][source]#

Get all commits since a specific date.

Parameters:

date_str – Date string (supports multiple formats via dateutil)
cwd – Working directory for the git command

Returns:

List of (sha, message) tuples

get_commits_since_commit( commit_sha: str, cwd: str | None = None, ) → list[tuple[str, str]][source]#

Get all commits since a specific commit (exclusive).

Parameters:

commit_sha – Commit SHA to start from (this commit is excluded)
cwd – Working directory for the git command

Returns:

List of (sha, message) tuples

parse_date_fallback(date_str: str) → str[source]#

Parse a date string without dateutil, trying common formats.

Parameters:: date_str – Date string to parse
Returns:: ISO 8601 formatted date string
Raises:: ValueError – If the date cannot be parsed

>>> parse_date_fallback("2026/01/15")
'2026-01-15T00:00:00'
>>> parse_date_fallback("2026-01-15")
'2026-01-15T00:00:00'
>>> parse_date_fallback("2026-01-15 14:30:00")
'2026-01-15T14:30:00'
>>> parse_date_fallback("2026-01-15T14:30:00")
'2026-01-15T14:30:00'

parse_commit_log(output: str) → list[tuple[str, str]][source]#

Parse git log output into a list of (sha, message) tuples.

Parameters:: output – Output from git log command
Returns:: List of (sha, full_message) tuples

get_remotes(cwd: str | None = None) → dict[str, str][source]#

Get all git remotes and their URLs.

Parameters:: cwd – Working directory for the git command
Returns:: Dictionary mapping remote names to their push URLs

parse_remote_url( remote_url: str, ) → tuple[str, str, str] | None[source]#

Parse a git remote URL to extract hosting info.

Supports: - SSH format: git@github.com:user/repo.git - SSH format: git@gitlab.example.com:group/repo.git - HTTPS format: https://github.com/user/repo.git - HTTPS format: https://gitlab.example.com/group/repo.git

Parameters:

remote_url – Git remote URL

Returns:

(host_type, base_url, repo_path) or None if cannot parse: host_type: host_type: “github”, “gitlab”, or “unknown” base_url: Base URL for the repository (e.g., “https://github.com/user/repo”) repo_path: Repository path (e.g., “user/repo”)

>>> parse_remote_url("git@github.com:Stoupy51/stouputils.git")
('github', 'https://github.com/Stoupy51/stouputils', 'Stoupy51/stouputils')
>>> parse_remote_url("https://github.com/Stoupy51/stouputils.git")
('github', 'https://github.com/Stoupy51/stouputils', 'Stoupy51/stouputils')
>>> parse_remote_url("git@gitlab.example.com:group/project.git")
('gitlab', 'https://gitlab.example.com/group/project', 'group/project')
>>> parse_remote_url("https://gitlab.company.com/team/repo.git")
('gitlab', 'https://gitlab.company.com/team/repo', 'team/repo')
>>> parse_remote_url("git@custom-server.com:user/repo.git")
('gitlab', 'https://custom-server.com/user/repo', 'user/repo')
>>> parse_remote_url("invalid-url") is None
True

detect_host_type(host: str) → str[source]#

Detect the type of git hosting service from hostname.

Parameters:: host – Hostname (e.g., “github.com”, “gitlab.example.com”)
Returns:: “github”, “gitlab”, or “unknown”

>>> detect_host_type("github.com")
'github'
>>> detect_host_type("gitlab.com")
'gitlab'
>>> detect_host_type("gitlab.example.com")
'gitlab'
>>> detect_host_type("custom-server.com")
'gitlab'
>>> detect_host_type("my-github-mirror.org")
'github'

create_url_formatter( remote_url: str, ) → tuple[Callable[[str], str], Callable[[str, str], str]] | None[source]#

Create URL formatter functions for a git remote.

Parameters:

remote_url – Git remote URL

Returns:

(commit_url_formatter, compare_url_formatter) or None.: The compare formatter takes two git refs as they are, a tag name or a commit SHA.

>>> commit_url, compare_url = create_url_formatter("git@github.com:Stoupy51/stouputils.git")
>>> commit_url("847b27e")
'https://github.com/Stoupy51/stouputils/commit/847b27e'
>>> compare_url("v1.9.0", "847b27e")
'https://github.com/Stoupy51/stouputils/compare/v1.9.0...847b27e'

generate_local_changelog( mode: str = 'tag', value: str | None = None, remote: str | None = None, cwd: str | None = None, ) → str[source]#

Generate a changelog from local git history.

Parameters:

mode – Mode for selecting commits - “tag”, “date”, or “commit”
value – Value for the mode (tag name, date, or commit SHA). If None and mode is “tag”, uses the latest tag.
remote – Remote name to use for commit URLs. If None, no URLs are generated.
cwd – Working directory for git commands

Returns:

Generated changelog in Markdown format

local_commits( mode: str, value: str | None, cwd: str | None, ) → tuple[list[tuple[str, str]], str | None][source]#

The commits a local changelog covers, and the git ref its comparison link starts from.

Parameters:

mode – “tag”, “date” or “commit”.
value – Tag name, date or commit SHA, the latest tag being used when None in “tag” mode.

Returns:

The (sha, message) commits, and the starting tag or commit, None in “date” mode or when the repository has no tag.

Raises:

ValueError – If the mode is unknown, or its value missing in “date” and “commit” modes.

remote_url_formatters( remote: str | None, cwd: str | None, ) → tuple[Callable[[str], str] | None, Callable[[str, str], str] | None][source]#: The commit and comparison URL formatters of a git remote, both None without a remote or when it cannot be read.

changelog_cli() → None[source]#

CLI interface for generating changelogs from local git history.

Usage:: stouputils changelog [tag|date|commit] [value] [–remote <remote>] [-o <file>]

stouputils changelog # Uses latest tag (default) stouputils changelog tag v1.9.0 # All commits since tag v1.9.0 stouputils changelog date 2026/01/05 # All commits since date stouputils changelog commit 847b27e # All commits since commit stouputils changelog –remote origin # Use origin remote for commit and comparison URLs stouputils changelog -o CHANGELOG.md # Output to file