API Reference¶

This page provides live API documentation for Gira's CLI commands and utilities using MkDocs' mkdocstrings plugin.

Live Documentation

This page shows live API documentation generated from the source code docstrings. For the complete CLI command reference, see CLI Reference.

Core Utilities¶

gira.utils.git_integration ¶

Git integration utilities for finding ticket references.

find_ticket_references_in_commits ¶

find_ticket_references_in_commits(
    ticket_id: str,
    repo_path: Optional[Path] = None,
    limit: int = 50,
) -> List[Dict[str, str]]

Find commits that reference a ticket ID.

Parameters:

Name	Type	Description	Default
`ticket_id`	`str`	The ticket ID to search for	required
`repo_path`	`Optional[Path]`	Path to git repository (defaults to current directory)	`None`
`limit`	`int`	Maximum number of commits to return	`50`

Returns:

Type	Description
`List[Dict[str, str]]`	List of dicts with 'sha' and 'message' keys

gira.utils.config ¶

Configuration utilities for Gira.

get_default_reporter ¶

get_default_reporter() -> str

Get default reporter from git config or gira config.

get_global_config ¶

get_global_config() -> Optional[GiraConfig]

Get the Gira configuration, checking project config first, then global.

get_valid_statuses ¶

get_valid_statuses() -> List[str]

Get list of valid statuses from board configuration or config file.

DEPRECATED: Use gira.utils.board_config.get_valid_statuses() instead. This function is maintained for backward compatibility and will be removed in a future version.

Returns statuses in priority order: 1. Board configuration swimlanes 2. Config file statuses 3. Default statuses

load_board_config ¶

load_board_config() -> Board

Load board configuration from project root or use default.

DEPRECATED: Use gira.utils.board_config.get_board_configuration() instead. This function is maintained for backward compatibility and will be removed in a future version.

load_config ¶

load_config() -> Dict[str, Any]

Load the Gira project configuration file.

save_config ¶

save_config(config: Dict[str, Any]) -> None

Save the Gira project configuration file.

Constants and Configuration¶

gira.constants ¶

Constants used throughout the Gira application.

get_project_prefix ¶

get_project_prefix() -> str

Get the current project's ticket ID prefix from config.

Returns:

Type	Description
`str`	The ticket ID prefix (e.g., "GCM")

Raises:

Type	Description
`ValueError`	If not in a Gira project or config is invalid

normalize_epic_id ¶

normalize_epic_id(epic_id: str) -> str

Normalize epic ID to use zero-padded format (e.g., EPIC-1 -> EPIC-001).

normalize_status ¶

normalize_status(status: str) -> str

Normalize status input to valid status value.

normalize_ticket_id ¶

normalize_ticket_id(
    ticket_id: str, prefix: str = None
) -> str

Normalize ticket ID by adding project prefix if needed.

Parameters:

Name	Type	Description	Default
`ticket_id`	`str`	The ticket ID to normalize (e.g., "673" or "GCM-673")	required
`prefix`	`str`	The project prefix to use. If None, must be provided in config.	`None`

Returns:

Type	Description
`str`	Normalized ticket ID (e.g., "GCM-673")

Examples:

normalize_ticket_id("673", "GCM") -> "GCM-673" normalize_ticket_id("GCM-673", "GCM") -> "GCM-673" normalize_ticket_id("ABC-123", "GCM") -> "ABC-123" (preserves existing prefix)

parse_ticket_id_pattern ¶

parse_ticket_id_pattern(
    pattern: str, prefix: str = None
) -> str

Parse ticket ID patterns, adding prefix to number-only patterns.

Handles: - Single IDs: "673" -> "GCM-673" - Ranges: "670..673" -> "GCM-670..673" - Wildcards: "67*" -> "GCM-67*" - Mixed: "GCM-670..673" -> "GCM-670..673" (unchanged)

Parameters:

Name	Type	Description	Default
`pattern`	`str`	The pattern to parse	required
`prefix`	`str`	The project prefix to use	`None`

Returns:

Type	Description
`str`	Normalized pattern with prefix added where needed