Skip to main content

Git Operations - API Specification

Introduction​

This document specifies the Application Programming Interface (API) for the git_operations module. The module provides a comprehensive, production-ready interface for all Git operations within the Codomyrmex ecosystem, supporting complete Git workflows with 40+ operations covering all aspects of Git repository management.

Note: This document contains the complete API specification with all function signatures, parameters, return types, and examples.

Core Operations​

check_git_availability() -> bool​

  • Description: Verifies that Git is installed and accessible on the system.
  • Parameters: None
  • Returns: bool - True if Git is available, False otherwise
  • Raises: None (returns False on errors)

is_git_repository(repository_path: str | None = None) -> bool​

  • Description: Checks if the specified path (or current directory) is a Git repository.
  • Parameters:
    • repository_path (str, optional): Path to check. Defaults to current working directory.
  • Returns: bool - True if path is a Git repository, False otherwise
  • Raises: None (returns False on errors)

initialize_git_repository(repository_path: str, initial_commit: bool = True) -> bool​

  • Description: Creates a new Git repository at the specified path with optional initial commit.
  • Parameters:
    • repository_path (str): Directory path where the repository will be created
    • initial_commit (bool, optional): Whether to create an initial commit with README.md. Defaults to True.
  • Returns: bool - True if repository was created successfully, False otherwise
  • Raises: None (returns False on errors)

clone_repository(url: str, destination: str, branch: str = None) -> bool​

  • Description: Clones a remote Git repository to the specified local destination.
  • Parameters:
    • url (str): Remote repository URL to clone
    • destination (str): Local directory path for the cloned repository
    • branch (str, optional): Specific branch to clone. Defaults to repository default.
  • Returns: bool - True if repository was cloned successfully, False otherwise
  • Raises: None (returns False on errors)

Branch Operations​

create_branch(branch_name: str, repository_path: str = None) -> bool​

  • Description: Creates a new branch and switches to it.
  • Parameters:
    • branch_name (str): Name of the new branch to create
    • repository_path (str, optional): Path to Git repository. Defaults to current directory.
  • Returns: bool - True if branch was created successfully, False otherwise

switch_branch(branch_name: str, repository_path: str = None) -> bool​

  • Description: Switches to an existing branch.
  • Parameters:
    • branch_name (str): Name of the branch to switch to
    • repository_path (str, optional): Path to Git repository. Defaults to current directory.
  • Returns: bool - True if branch switch was successful, False otherwise

get_current_branch(repository_path: str = None) -> Optional[str]​

  • Description: Gets the name of the currently active branch.
  • Parameters:
    • repository_path (str, optional): Path to Git repository. Defaults to current directory.
  • Returns: Optional[str] - Name of the current branch, or None on error

merge_branch(source_branch: str, target_branch: str, repository_path: str = None) -> bool​

  • Description: Merges source branch into target branch.
  • Parameters:
    • source_branch (str): Branch to merge from
    • target_branch (str): Branch to merge into
    • repository_path (str, optional): Path to Git repository. Defaults to current directory.
  • Returns: bool - True if merge was successful, False otherwise

rebase_branch(target_branch: str, repository_path: str | None = None, interactive: bool = False) -> bool​

  • Description: Rebases the current branch onto target_branch.
  • Parameters:
    • target_branch (str): Branch to rebase onto
    • repository_path (str, optional): Path to Git repository. Defaults to current directory.
    • interactive (bool, optional): Run an interactive rebase. Defaults to False.
  • Returns: bool - True if rebase was successful, False otherwise

File Operations​

add_files(file_paths: list[str], repository_path: str = None) -> bool​

  • Description: Add files to the Git staging area.
  • Parameters:
    • file_paths (list[str]): List of file paths to add
    • repository_path (str, optional): Path to Git repository. Defaults to current directory.
  • Returns: bool - True if files were added successfully, False otherwise

commit_changes(message: str, repository_path: str = None) -> bool​

  • Description: Commit staged changes with the given message.
  • Parameters:
    • message (str): Commit message
    • repository_path (str, optional): Path to Git repository. Defaults to current directory.
  • Returns: bool - True if commit was successful, False otherwise

get_status(repository_path: str = None) -> dict[str, Any]​

  • Description: Get the current status of the repository.
  • Parameters:
    • repository_path (str, optional): Path to Git repository. Defaults to current directory.
  • Returns: dict[str, Any] - Dictionary containing status information (branch, changes, etc.)

get_diff(target: str | None = None, repository_path: str | None = None, cached: bool = False) -> str​

  • Description: Get the diff of changes in the repository.
  • Parameters:
    • target (str, optional): Revision to diff against (for example HEAD, main or a commit SHA). Without it, diffs the working tree against the index, or the index against HEAD when cached is True.
    • repository_path (str, optional): Path to Git repository. Defaults to current directory.
    • cached (bool, optional): Show staged changes (--cached). Defaults to False.
  • Returns: str - Diff output as string

reset_changes(repository_path: str = None, mode: str = "mixed") -> bool​

  • Description: Reset changes in the repository.
  • Parameters:
    • repository_path (str, optional): Path to Git repository. Defaults to current directory.
    • mode (str, optional): Reset mode ("mixed", "soft", "hard"). Defaults to "mixed".
  • Returns: bool - True if reset was successful, False otherwise

Remote Operations​

push_changes(remote: str = "origin", branch: str = None, repository_path: str = None) -> bool​

  • Description: Push committed changes to a remote repository.
  • Parameters:
    • remote (str, optional): Remote name. Defaults to "origin".
    • branch (str, optional): Branch to push. Defaults to current branch.
    • repository_path (str, optional): Path to Git repository. Defaults to current directory.
  • Returns: bool - True if push was successful, False otherwise

pull_changes(remote: str = "origin", branch: str = None, repository_path: str = None) -> bool​

  • Description: Pull changes from a remote repository.
  • Parameters:
    • remote (str, optional): Remote name. Defaults to "origin".
    • branch (str, optional): Branch to pull. Defaults to current branch.
    • repository_path (str, optional): Path to Git repository. Defaults to current directory.
  • Returns: bool - True if pull was successful, False otherwise

History & Information​

get_commit_history(limit: int = 10, repository_path: str | None = None) -> list[dict[str, str]]​

  • Description: Get recent commit history of the current branch.
  • Parameters:
    • limit (int, optional): Maximum number of commits to return. Defaults to 10.
    • repository_path (str, optional): Path to Git repository. Defaults to current directory.
  • Returns: list[dict[str, str]] - One dictionary per commit with hash, author_name, author_email, date and message; empty on error

Tag Operations​

create_tag(tag_name: str, message: str = None, repository_path: str = None) -> bool​

  • Description: Create a Git tag.
  • Parameters:
    • tag_name (str): Name of the tag
    • message (str, optional): Tag message
    • repository_path (str, optional): Path to Git repository. Defaults to current directory.
  • Returns: bool - True if tag was created successfully, False otherwise

list_tags(repository_path: str = None) -> list[str]​

  • Description: List all tags in the repository.
  • Parameters:
    • repository_path (str, optional): Path to Git repository. Defaults to current directory.
  • Returns: list[str] - List of tag names

Stash Operations​

stash_changes(message: str = None, repository_path: str = None) -> bool​

  • Description: Stash uncommitted changes.
  • Parameters:
    • message (str, optional): Stash message
    • repository_path (str, optional): Path to Git repository. Defaults to current directory.
  • Returns: bool - True if stash was successful, False otherwise

apply_stash(stash_ref: str = None, repository_path: str = None) -> bool​

  • Description: Apply a stash.
  • Parameters:
    • stash_ref (str, optional): Stash reference (e.g., "stash@0"). Defaults to most recent.
    • repository_path (str, optional): Path to Git repository. Defaults to current directory.
  • Returns: bool - True if stash was applied successfully, False otherwise

list_stashes(repository_path: str = None) -> list[dict[str, str]]​

  • Description: List all stashes.
  • Parameters:
    • repository_path (str, optional): Path to Git repository. Defaults to current directory.
  • Returns: list[dict[str, str]] - List of stash dictionaries with metadata

GitHub API Operations​

The module also provides GitHub API integration through the github_api submodule. See github_api.py for functions like:

  • create_github_repository()
  • create_pull_request()
  • get_pull_requests()
  • get_repository_info()

Visualization Integration​

When data_visualization module is available, the following functions are provided:

  • create_git_analysis_report()
  • visualize_git_branches()
  • visualize_commit_activity()
  • create_git_workflow_diagram()

See visualization_integration.py for details.

Data Models​

Repository Status Dictionary​

Returned by get_status():

{
    "branch": str,           # Current branch name
    "is_dirty": bool,        # Whether there are uncommitted changes
    "untracked_files": list[str],
    "modified_files": list[str],
    "staged_files": list[str],
    "ahead_by": int,        # Commits ahead of remote
    "behind_by": int         # Commits behind remote
}

Commit History Dictionary​

Returned by get_commit_history():

{
    "sha": str,              # Full commit SHA
    "short_sha": str,        # Short commit SHA
    "message": str,          # Commit message
    "author": str,           # Author name
    "email": str,            # Author email
    "date": str,             # Commit date (ISO format)
    "timestamp": float       # Unix timestamp
}

Authentication & Authorization​

  • Credential Management: The module relies on Git's underlying credential management system (SSH agent, Git Credential Manager, OS keychain). It does not directly handle or store credentials.
  • GitHub API: Requires a GitHub Personal Access Token (PAT) stored in environment variables or Git credential helper.
  • Security: See SECURITY.md for detailed security considerations.

Error Handling​

All functions return False or None on failure rather than raising exceptions. Errors are logged via the logging_monitoring module. Check function return values and logs for error details.

Rate Limiting​

  • Git Operations: No rate limiting (limited by system resources)
  • GitHub API: Subject to GitHub API rate limits (5,000 requests/hour for authenticated requests)

Versioning​

This API follows the Codomyrmex project versioning strategy. API stability is maintained for public functions. Internal implementations may change without notice.

Complete Documentation​

For comprehensive documentation with detailed examples, parameter descriptions, and usage patterns, see: