Git

Git utilities: branch analysis, operations, status, workflow, validation.

Git utilities for siege_utilities package. Comprehensive git operations, branch management, and status reporting.

exception siege_utilities.git.GitError[source]

Bases: SiegeError

Error executing a git command or git workflow operation.

siege_utilities.git.analyze_branch_status(repo_path='.')[source]

Analyze the current branch status.

Raises:: GitError – If the ahead/behind comparison against main fails.
Parameters:: repo_path (str)
Return type:: Dict[str, str]

siege_utilities.git.generate_branch_report(output_file=None, repo_path='.', include_commits=20)[source]

Generate a comprehensive branch status report.

Parameters:

output_file (str | None)
repo_path (str)
include_commits (int)

Return type:

str

siege_utilities.git.get_commit_history(limit=20, repo_path='.')[source]

Get recent commit history with details.

Parameters:

limit (int)
repo_path (str)

Return type:

List[Dict[str, str]]

siege_utilities.git.categorize_commits(commits)[source]

Categorize commits by type and purpose.

Parameters:: commits (List[Dict[str, str]])
Return type:: Dict[str, List[Dict[str, str]]]

siege_utilities.git.get_file_changes(repo_path='.')[source]

Get files that differ from main branch.

Raises:: GitError – If the diff comparison against main fails.
Parameters:: repo_path (str)
Return type:: Dict[str, List[str]]

siege_utilities.git.create_feature_branch(branch_name, base_branch='main', repo_path='.', switch_to_branch=True)[source]

Create a new feature branch from base branch.

Parameters:

branch_name (str)
base_branch (str)
repo_path (str)
switch_to_branch (bool)

Return type:

Dict[str, str]

siege_utilities.git.switch_branch(branch_name, repo_path='.')[source]

Switch to an existing branch.

SECURITY: Validates branch names to prevent command injection.

Parameters:

branch_name (str) – Name of branch to switch to
repo_path (str) – Repository path

Returns:

Dictionary with switch status

Raises:

GitSecurityError – If branch name fails validation

Return type:

Dict[str, str]

siege_utilities.git.merge_branch(source_branch, target_branch='main', repo_path='.', fast_forward_only=False, squash=False)[source]

Merge a source branch into target branch.

SECURITY: Validates branch names to prevent command injection.

Parameters:

source_branch (str) – Branch to merge from
target_branch (str) – Branch to merge into
repo_path (str) – Repository path
fast_forward_only (bool) – Only allow fast-forward merges
squash (bool) – Squash commits during merge

Returns:

Dictionary with merge status

Raises:

GitSecurityError – If branch names fail validation

Return type:

Dict[str, str]

siege_utilities.git.rebase_branch(source_branch, base_branch='main', repo_path='.', interactive=False)[source]

Rebase a branch onto another branch.

SECURITY: Validates branch names to prevent command injection.

Parameters:

source_branch (str) – Branch to rebase
base_branch (str) – Branch to rebase onto
repo_path (str) – Repository path
interactive (bool) – Use interactive rebase

Returns:

Dictionary with rebase status

Raises:

GitSecurityError – If branch names fail validation

Return type:

Dict[str, str]

siege_utilities.git.stash_changes(message=None, include_untracked=False, repo_path='.')[source]

Stash current changes.

SECURITY: Validates commit message to prevent command injection.

Parameters:

message (str | None) – Optional stash message
include_untracked (bool) – Include untracked files
repo_path (str) – Repository path

Returns:

Dictionary with stash status

Raises:

GitSecurityError – If message fails validation

Return type:

Dict[str, str]

siege_utilities.git.apply_stash(stash_ref='stash@{0}', repo_path='.', pop=False)[source]

Apply a stashed change.

SECURITY: Validates stash reference to prevent command injection.

Parameters:

stash_ref (str) – Stash reference (e.g., “stash@{0}”)
repo_path (str) – Repository path
pop (bool) – Pop instead of apply

Returns:

Dictionary with apply status

Raises:

GitSecurityError – If stash ref fails validation

Return type:

Dict[str, str]

siege_utilities.git.clean_working_directory(repo_path='.', force=False, directories=False, interactive=True)[source]

Clean untracked files from working directory.

Parameters:

interactive (bool) – When False, skip the confirmation prompt (safe for CI). When True (default), prompt the user before cleaning.
repo_path (str)
force (bool)
directories (bool)

Return type:

Dict[str, str]

siege_utilities.git.reset_to_commit(commit_hash, reset_type='soft', repo_path='.')[source]

Reset HEAD to a specific commit.

SECURITY: Validates commit hash to prevent command injection.

Parameters:

commit_hash (str) – Commit SHA to reset to
reset_type (str) – Type of reset (soft, mixed, hard)
repo_path (str) – Repository path

Returns:

Dictionary with reset status

Raises:

GitSecurityError – If commit hash fails validation

Return type:

Dict[str, str]

siege_utilities.git.cherry_pick_commit(commit_hash, repo_path='.', continue_on_conflict=False)[source]

Cherry-pick a specific commit.

SECURITY: Validates commit hash to prevent command injection.

Parameters:

commit_hash (str) – Commit SHA to cherry-pick
repo_path (str) – Repository path
continue_on_conflict (bool) – Continue after resolving conflicts

Returns:

Dictionary with cherry-pick status

Raises:

GitSecurityError – If commit hash fails validation

Return type:

Dict[str, str]

siege_utilities.git.create_tag(tag_name, message=None, commit_hash=None, repo_path='.', push=False)[source]

Create a git tag.

SECURITY: This function validates tag names to prevent command injection and invalid git references.

Parameters:

tag_name (str) – Name for the tag
message (str | None) – Optional tag message
commit_hash (str | None) – Optional specific commit to tag
repo_path (str) – Repository path (default: current directory)
push (bool) – Whether to push tag to remote

Returns:

Dictionary with tag creation status

Raises:

GitSecurityError – If tag name, message, or commit hash fails validation

Return type:

Dict[str, str]

Example

>>> result = create_tag("v1.0.0", message="Release 1.0.0")
>>>
>>> # This will raise GitSecurityError
>>> create_tag("<script>alert('xss')</script>")  # Invalid tag name

Security Changes:

Now validates tag names against git ref name rules
Blocks command injection patterns
Validates commit hash format
Validates commit message content

siege_utilities.git.push_branch(branch_name=None, remote='origin', force=False, repo_path='.')[source]

Push a branch to remote.

SECURITY: Validates branch and remote names to prevent command injection.

Parameters:

branch_name (str | None) – Branch to push (None for current branch)
remote (str) – Remote repository name
force (bool) – Force push with lease
repo_path (str) – Repository path

Returns:

Dictionary with push status

Raises:

GitSecurityError – If branch or remote name fails validation

Return type:

Dict[str, str]

siege_utilities.git.pull_branch(branch_name=None, remote='origin', rebase=False, repo_path='.')[source]

Pull changes from remote branch.

SECURITY: Validates branch and remote names to prevent command injection.

Parameters:

branch_name (str | None) – Branch to pull (None for current branch)
remote (str) – Remote repository name
rebase (bool) – Rebase instead of merge
repo_path (str) – Repository path

Returns:

Dictionary with pull status

Raises:

GitSecurityError – If branch or remote name fails validation

Return type:

Dict[str, str]

siege_utilities.git.get_repository_status(repo_path='.')[source]

Get comprehensive repository status information.

Raises:

ValueError – If repo_path is not a git repository.
GitError – If any git command fails while gathering status.

Parameters:

repo_path (str)

Return type:

Dict[str, str | int | bool]

siege_utilities.git.get_branch_info(repo_path='.')[source]

Get detailed information about all branches.

Raises:: GitError – If any git command fails while gathering branch info.
Parameters:: repo_path (str)
Return type:: Dict[str, str | List[str] | int]

siege_utilities.git.get_remote_info(repo_path='.')[source]

Get information about remote repositories.

Raises:: GitError – If any git command fails while gathering remote info.
Parameters:: repo_path (str)
Return type:: Dict[str, str | List[Dict[str, str]]]

siege_utilities.git.get_stash_list(repo_path='.')[source]

Get list of stashed changes.

Raises:: GitError – If the git stash list command fails.
Parameters:: repo_path (str)
Return type:: List[Dict[str, str]]

siege_utilities.git.get_tag_list(repo_path='.')[source]

Get list of tags with details.

Raises:: GitError – If the git tag list command fails.
Parameters:: repo_path (str)
Return type:: List[Dict[str, str]]

siege_utilities.git.get_log_summary(since=None, until=None, author=None, repo_path='.', max_count=100)[source]

Get a summary of commit logs with filtering options.

Raises:

GitError – If the git log command fails.

Parameters:

since (str | None)
until (str | None)
author (str | None)
repo_path (str)
max_count (int)

Return type:

Dict[str, int | List[Dict[str, str]]]

siege_utilities.git.start_feature_workflow(feature_name, base_branch='main', repo_path='.', auto_push=True)[source]

Start a new feature development workflow.

Parameters:

feature_name (str)
base_branch (str)
repo_path (str)
auto_push (bool)

Return type:

Dict[str, str | bool | Dict[str, str]]

siege_utilities.git.complete_feature_workflow(feature_branch, target_branch='main', repo_path='.', squash=True, delete_branch=True)[source]

Complete a feature development workflow.

Parameters:

feature_branch (str)
target_branch (str)
repo_path (str)
squash (bool)
delete_branch (bool)

Return type:

Dict[str, str | bool | Dict[str, str]]

siege_utilities.git.hotfix_workflow(hotfix_name, base_branch='main', repo_path='.', auto_push=True)[source]

Start a hotfix workflow for urgent fixes.

Parameters:

hotfix_name (str)
base_branch (str)
repo_path (str)
auto_push (bool)

Return type:

Dict[str, str | bool | Dict[str, str]]

siege_utilities.git.release_workflow(version, base_branch='main', repo_path='.', auto_push=True)[source]

Start a release workflow for version releases.

Parameters:

version (str)
base_branch (str)
repo_path (str)
auto_push (bool)

Return type:

Dict[str, str | bool | Dict[str, str]]

siege_utilities.git.validate_branch_naming(branch_name)[source]

Validate branch naming conventions.

Parameters:: branch_name (str)
Return type:: Dict[str, bool | str | List[str]]

siege_utilities.git.enforce_commit_conventions(commit_message)[source]

Enforce conventional commit message format.

Parameters:: commit_message (str)
Return type:: Dict[str, bool | str | List[str]]

Submodules

Branch analysis utilities for git repositories. Based on the Change-Agent-AI branch status generator.

siege_utilities.git.branch_analyzer.analyze_branch_status(repo_path='.')[source]

Analyze the current branch status.

Raises:: GitError – If the ahead/behind comparison against main fails.
Parameters:: repo_path (str)
Return type:: Dict[str, str]

siege_utilities.git.branch_analyzer.get_commit_history(limit=20, repo_path='.')[source]

Get recent commit history with details.

Parameters:

limit (int)
repo_path (str)

Return type:

List[Dict[str, str]]

siege_utilities.git.branch_analyzer.categorize_commits(commits)[source]

Categorize commits by type and purpose.

Parameters:: commits (List[Dict[str, str]])
Return type:: Dict[str, List[Dict[str, str]]]

siege_utilities.git.branch_analyzer.get_file_changes(repo_path='.')[source]

Get files that differ from main branch.

Raises:: GitError – If the diff comparison against main fails.
Parameters:: repo_path (str)
Return type:: Dict[str, List[str]]

siege_utilities.git.branch_analyzer.get_file_stats(repo_path='.')[source]

Get statistics about file changes.

Parameters:: repo_path (str)
Return type:: Dict[str, int]

siege_utilities.git.branch_analyzer.generate_branch_report(output_file=None, repo_path='.', include_commits=20)[source]

Generate a comprehensive branch status report.

Parameters:

output_file (str | None)
repo_path (str)
include_commits (int)

Return type:

str

Git operations utilities for repository management. Comprehensive git commands and workflow automation.

siege_utilities.git.git_operations.create_feature_branch(branch_name, base_branch='main', repo_path='.', switch_to_branch=True)[source]

Create a new feature branch from base branch.

Parameters:

branch_name (str)
base_branch (str)
repo_path (str)
switch_to_branch (bool)

Return type:

Dict[str, str]

siege_utilities.git.git_operations.switch_branch(branch_name, repo_path='.')[source]

Switch to an existing branch.

SECURITY: Validates branch names to prevent command injection.

Parameters:

branch_name (str) – Name of branch to switch to
repo_path (str) – Repository path

Returns:

Dictionary with switch status

Raises:

GitSecurityError – If branch name fails validation

Return type:

Dict[str, str]

siege_utilities.git.git_operations.merge_branch(source_branch, target_branch='main', repo_path='.', fast_forward_only=False, squash=False)[source]

Merge a source branch into target branch.

SECURITY: Validates branch names to prevent command injection.

Parameters:

source_branch (str) – Branch to merge from
target_branch (str) – Branch to merge into
repo_path (str) – Repository path
fast_forward_only (bool) – Only allow fast-forward merges
squash (bool) – Squash commits during merge

Returns:

Dictionary with merge status

Raises:

GitSecurityError – If branch names fail validation

Return type:

Dict[str, str]

siege_utilities.git.git_operations.rebase_branch(source_branch, base_branch='main', repo_path='.', interactive=False)[source]

Rebase a branch onto another branch.

SECURITY: Validates branch names to prevent command injection.

Parameters:

source_branch (str) – Branch to rebase
base_branch (str) – Branch to rebase onto
repo_path (str) – Repository path
interactive (bool) – Use interactive rebase

Returns:

Dictionary with rebase status

Raises:

GitSecurityError – If branch names fail validation

Return type:

Dict[str, str]

siege_utilities.git.git_operations.stash_changes(message=None, include_untracked=False, repo_path='.')[source]

Stash current changes.

SECURITY: Validates commit message to prevent command injection.

Parameters:

message (str | None) – Optional stash message
include_untracked (bool) – Include untracked files
repo_path (str) – Repository path

Returns:

Dictionary with stash status

Raises:

GitSecurityError – If message fails validation

Return type:

Dict[str, str]

siege_utilities.git.git_operations.apply_stash(stash_ref='stash@{0}', repo_path='.', pop=False)[source]

Apply a stashed change.

SECURITY: Validates stash reference to prevent command injection.

Parameters:

stash_ref (str) – Stash reference (e.g., “stash@{0}”)
repo_path (str) – Repository path
pop (bool) – Pop instead of apply

Returns:

Dictionary with apply status

Raises:

GitSecurityError – If stash ref fails validation

Return type:

Dict[str, str]

siege_utilities.git.git_operations.clean_working_directory(repo_path='.', force=False, directories=False, interactive=True)[source]

Clean untracked files from working directory.

Parameters:

interactive (bool) – When False, skip the confirmation prompt (safe for CI). When True (default), prompt the user before cleaning.
repo_path (str)
force (bool)
directories (bool)

Return type:

Dict[str, str]

siege_utilities.git.git_operations.reset_to_commit(commit_hash, reset_type='soft', repo_path='.')[source]

Reset HEAD to a specific commit.

SECURITY: Validates commit hash to prevent command injection.

Parameters:

commit_hash (str) – Commit SHA to reset to
reset_type (str) – Type of reset (soft, mixed, hard)
repo_path (str) – Repository path

Returns:

Dictionary with reset status

Raises:

GitSecurityError – If commit hash fails validation

Return type:

Dict[str, str]

siege_utilities.git.git_operations.cherry_pick_commit(commit_hash, repo_path='.', continue_on_conflict=False)[source]

Cherry-pick a specific commit.

SECURITY: Validates commit hash to prevent command injection.

Parameters:

commit_hash (str) – Commit SHA to cherry-pick
repo_path (str) – Repository path
continue_on_conflict (bool) – Continue after resolving conflicts

Returns:

Dictionary with cherry-pick status

Raises:

GitSecurityError – If commit hash fails validation

Return type:

Dict[str, str]

siege_utilities.git.git_operations.create_tag(tag_name, message=None, commit_hash=None, repo_path='.', push=False)[source]

Create a git tag.

SECURITY: This function validates tag names to prevent command injection and invalid git references.

Parameters:

tag_name (str) – Name for the tag
message (str | None) – Optional tag message
commit_hash (str | None) – Optional specific commit to tag
repo_path (str) – Repository path (default: current directory)
push (bool) – Whether to push tag to remote

Returns:

Dictionary with tag creation status

Raises:

GitSecurityError – If tag name, message, or commit hash fails validation

Return type:

Dict[str, str]

Example

>>> result = create_tag("v1.0.0", message="Release 1.0.0")
>>>
>>> # This will raise GitSecurityError
>>> create_tag("<script>alert('xss')</script>")  # Invalid tag name

Security Changes:

Now validates tag names against git ref name rules
Blocks command injection patterns
Validates commit hash format
Validates commit message content

siege_utilities.git.git_operations.push_branch(branch_name=None, remote='origin', force=False, repo_path='.')[source]

Push a branch to remote.

SECURITY: Validates branch and remote names to prevent command injection.

Parameters:

branch_name (str | None) – Branch to push (None for current branch)
remote (str) – Remote repository name
force (bool) – Force push with lease
repo_path (str) – Repository path

Returns:

Dictionary with push status

Raises:

GitSecurityError – If branch or remote name fails validation

Return type:

Dict[str, str]

siege_utilities.git.git_operations.pull_branch(branch_name=None, remote='origin', rebase=False, repo_path='.')[source]

Pull changes from remote branch.

SECURITY: Validates branch and remote names to prevent command injection.

Parameters:

branch_name (str | None) – Branch to pull (None for current branch)
remote (str) – Remote repository name
rebase (bool) – Rebase instead of merge
repo_path (str) – Repository path

Returns:

Dictionary with pull status

Raises:

GitSecurityError – If branch or remote name fails validation

Return type:

Dict[str, str]

Git status utilities for repository information and reporting. Comprehensive repository state analysis and monitoring.

siege_utilities.git.git_status.get_repository_status(repo_path='.')[source]

Get comprehensive repository status information.

Raises:

ValueError – If repo_path is not a git repository.
GitError – If any git command fails while gathering status.

Parameters:

repo_path (str)

Return type:

Dict[str, str | int | bool]

siege_utilities.git.git_status.get_branch_info(repo_path='.')[source]

Get detailed information about all branches.

Raises:: GitError – If any git command fails while gathering branch info.
Parameters:: repo_path (str)
Return type:: Dict[str, str | List[str] | int]

siege_utilities.git.git_status.get_remote_info(repo_path='.')[source]

Get information about remote repositories.

Raises:: GitError – If any git command fails while gathering remote info.
Parameters:: repo_path (str)
Return type:: Dict[str, str | List[Dict[str, str]]]

siege_utilities.git.git_status.get_stash_list(repo_path='.')[source]

Get list of stashed changes.

Raises:: GitError – If the git stash list command fails.
Parameters:: repo_path (str)
Return type:: List[Dict[str, str]]

siege_utilities.git.git_status.get_tag_list(repo_path='.')[source]

Get list of tags with details.

Raises:: GitError – If the git tag list command fails.
Parameters:: repo_path (str)
Return type:: List[Dict[str, str]]

siege_utilities.git.git_status.get_log_summary(since=None, until=None, author=None, repo_path='.', max_count=100)[source]

Get a summary of commit logs with filtering options.

Raises:

GitError – If the git log command fails.

Parameters:

since (str | None)
until (str | None)
author (str | None)
repo_path (str)
max_count (int)

Return type:

Dict[str, int | List[Dict[str, str]]]

siege_utilities.git.git_status.get_file_status(repo_path='.')[source]

Get detailed status of all files in the repository.

Raises:: GitError – If the git status command fails.
Parameters:: repo_path (str)
Return type:: Dict[str, List[str]]

siege_utilities.git.git_status.get_repository_size(repo_path='.')[source]

Get repository size information.

Raises:: GitError – If repository size cannot be calculated.
Parameters:: repo_path (str)
Return type:: Dict[str, int | str]

Git workflow utilities for automated git operations and best practices. Standardized workflows for feature development, releases, and hotfixes.

siege_utilities.git.git_workflow.validate_branch_naming(branch_name)[source]

Validate branch naming conventions.

Parameters:: branch_name (str)
Return type:: Dict[str, bool | str | List[str]]

siege_utilities.git.git_workflow.enforce_commit_conventions(commit_message)[source]

Enforce conventional commit message format.

Parameters:: commit_message (str)
Return type:: Dict[str, bool | str | List[str]]

siege_utilities.git.git_workflow.start_feature_workflow(feature_name, base_branch='main', repo_path='.', auto_push=True)[source]

Start a new feature development workflow.

Parameters:

feature_name (str)
base_branch (str)
repo_path (str)
auto_push (bool)

Return type:

Dict[str, str | bool | Dict[str, str]]

siege_utilities.git.git_workflow.complete_feature_workflow(feature_branch, target_branch='main', repo_path='.', squash=True, delete_branch=True)[source]

Complete a feature development workflow.

Parameters:

feature_branch (str)
target_branch (str)
repo_path (str)
squash (bool)
delete_branch (bool)

Return type:

Dict[str, str | bool | Dict[str, str]]

siege_utilities.git.git_workflow.hotfix_workflow(hotfix_name, base_branch='main', repo_path='.', auto_push=True)[source]

Start a hotfix workflow for urgent fixes.

Parameters:

hotfix_name (str)
base_branch (str)
repo_path (str)
auto_push (bool)

Return type:

Dict[str, str | bool | Dict[str, str]]

siege_utilities.git.git_workflow.release_workflow(version, base_branch='main', repo_path='.', auto_push=True)[source]

Start a release workflow for version releases.

Parameters:

version (str)
base_branch (str)
repo_path (str)
auto_push (bool)

Return type:

Dict[str, str | bool | Dict[str, str]]

siege_utilities.git.git_workflow.get_workflow_status(repo_path='.')[source]

Get the current workflow status of the repository.

Parameters:: repo_path (str)
Return type:: Dict[str, str | List[str] | Dict[str, str]]

Git input validation and sanitization utilities.

This module provides security-focused input validation for git operations to prevent: - Command injection in git commands - Invalid/malicious branch names, tag names, commit messages - Path traversal in repository paths - Dangerous git command patterns

Use these validators in all git operations to ensure secure command execution.

exception siege_utilities.git.validation.GitSecurityError[source]

Bases: Exception

Raised when git input fails security validation.

siege_utilities.git.validation.validate_branch_name(branch_name)[source]

Validate a git branch name.

Parameters:: branch_name (str) – Branch name to validate
Returns:: Validated branch name
Raises:: GitSecurityError – If branch name fails validation
Return type:: str

Example

>>> validate_branch_name("feature/authentication")
'feature/authentication'
>>> validate_branch_name("branch$(cat /etc/passwd)")

siege_utilities.git.validation.validate_tag_name(tag_name)[source]

Validate a git tag name.

Parameters:: tag_name (str) – Tag name to validate
Returns:: Validated tag name
Raises:: GitSecurityError – If tag name fails validation
Return type:: str

Example

>>> validate_tag_name("v1.0.0")
'v1.0.0'
>>> validate_tag_name("<script>alert('xss')</script>")

siege_utilities.git.validation.validate_commit_message(message, max_length=10000)[source]

Validate a git commit message.

Parameters:

message (str) – Commit message to validate
max_length (int) – Maximum allowed length

Returns:

Validated commit message

Raises:

GitSecurityError – If message fails validation
ValueError – If message is invalid

Return type:

str

Example

>>> validate_commit_message("Fix bug in authentication")
'Fix bug in authentication'
>>> validate_commit_message("Message; rm -rf /")

siege_utilities.git.validation.validate_commit_hash(commit_hash)[source]

Validate a git commit hash (SHA).

Parameters:

commit_hash (str) – Commit hash to validate (short or full)

Returns:

Validated commit hash

Raises:

GitSecurityError – If commit hash fails validation
ValueError – If commit hash is invalid

Return type:

str

Example

>>> validate_commit_hash("a1b2c3d")
'a1b2c3d'
>>> validate_commit_hash("abc123; rm -rf /")

siege_utilities.git.validation.validate_remote_name(remote_name)[source]

Validate a git remote name.

Parameters:: remote_name (str) – Remote name to validate (e.g., “origin”)
Returns:: Validated remote name
Raises:: GitSecurityError – If remote name fails validation
Return type:: str

Example

>>> validate_remote_name("origin")
'origin'
>>> validate_remote_name("origin; curl evil.com")

siege_utilities.git.validation.validate_repo_path(repo_path)[source]

Validate a repository path.

Parameters:: repo_path (str) – Repository path to validate
Returns:: Validated Path object
Raises:: GitSecurityError – If path fails security validation
Return type:: Path

Example

>>> validate_repo_path(".")
>>> validate_repo_path("../../../etc")

siege_utilities.git.validation.validate_git_ref_name(ref_name, ref_type='ref')[source]

Validate a git reference name (branch, tag, remote).

Implements git-check-ref-format rules: - No path component starting with . - No double dots .. - No ASCII control characters, space, ~, ^, :, ?, *, [ - No ending with / - No ending with .lock - No @ with { following it - No backslashes

Parameters:

ref_name (str) – Reference name to validate
ref_type (str) – Type of reference (branch, tag, remote) for error messages

Returns:

Validated reference name

Raises:

GitSecurityError – If ref name fails validation
ValueError – If ref name is invalid

Return type:

str

Example

>>> validate_git_ref_name("feature/my-branch", "branch")
'feature/my-branch'
>>> validate_git_ref_name("branch; rm -rf /", "branch")

siege_utilities.git.validation.has_dangerous_characters(text)[source]

Check if text contains characters dangerous for git commands.

Parameters:: text (str) – Text to check
Returns:: True if text contains dangerous characters
Return type:: bool

Example

>>> has_dangerous_characters("branch-name")
False
>>> has_dangerous_characters("branch; rm -rf /")
True

Shared internal helpers for the git sub-package.

siege_utilities.git._utils.run_git_command(*args, repo_path='.', check=True)[source]

Run a git command and return stdout.

When check=True (default), raises GitError on non-zero exit. When check=False, returns "" on failure.

Note

# SU-1: intentional — check=False callers (upstream detection, # optional config reads, best-effort push/pull) explicitly expect # empty-string as a “not available” sentinel and handle it at the # call site. Do not remove this path without converting all callers # to try/except.

Parameters:

repo_path (str)
check (bool)

Return type:

str