Skip to main content

git_operations API Specification

Version: v1.3.0 | Status: Active | Last Updated: July 2026

Overview​

The git_operations module provides comprehensive Git workflow automation, repository management, and version control operations. It exposes both CLI and programmatic APIs for interacting with Git repositories.

Core API​

Repository Operations​

from codomyrmex.git_operations import (
    check_git_availability,
    is_git_repository,
    initialize_git_repository,
    clone_repository,
)

# Check git is installed
available = check_git_availability()  # -> bool

# Check if path is a git repo
is_repo = is_git_repository("/path/to/dir")  # -> bool

# Initialize a new repository
initialized = initialize_git_repository("/path/to/new/repo", initial_commit=True)  # -> bool

# Clone a repository
cloned = clone_repository(
    url="https://github.com/example/repo.git",
    destination="/path/to/local",
    branch="main",
)  # -> bool

File and Commit Operations​

from codomyrmex.git_operations import (
    add_files,
    commit_changes,
    get_status,
    get_diff,
    reset_changes,
)

# Stage files
add_files(["file1.py", "file2.py"], repository_path="/path/to/repo")  # -> bool

# Create commit
commit_hash = commit_changes(
    message="Add new feature",
    repository_path="/path/to/repo",
    author_name="Developer",
    author_email="dev@example.com",
    stage_all=True,
)  # -> str | None

# Get repository status
status = get_status(repository_path="/path/to/repo")  # -> dict

# Get diff
diff = get_diff(target="HEAD", repository_path="/path/to/repo", cached=False)  # -> str

# Reset changes
reset_changes(mode="mixed", target="HEAD", repository_path="/path/to/repo")  # -> bool

Branch Operations​

from codomyrmex.git_operations import (
    create_branch,
    switch_branch,
    get_current_branch,
    list_branches,
    delete_branch,
    merge_branch,
)

# Create branch
create_branch("feature/new-feature", repository_path="/path/to/repo")  # -> bool

# Switch to branch
switch_branch("feature/new-feature", repository_path="/path/to/repo")  # -> bool

# Get current branch
branch = get_current_branch(repository_path="/path/to/repo")  # -> str | None

# List branches
branches = list_branches(repository_path="/path/to/repo")  # -> list[str]

# Delete branch
delete_branch("feature/old", repository_path="/path/to/repo", force=False)  # -> bool

# Merge branch
merge_branch(
    source_branch="feature/new-feature",
    target_branch="main",
    repository_path="/path/to/repo",
    strategy=None,
)  # -> bool

Remote Operations​

from codomyrmex.git_operations import (
    push_changes,
    pull_changes,
    fetch_changes,
    add_remote,
)

# Add remote
add_remote("upstream", "https://github.com/upstream/repo.git", repository_path="/path/to/repo")  # -> bool

# Fetch updates
fetch_changes(remote="origin", branch=None, repository_path="/path/to/repo", prune=False)  # -> bool

# Pull changes
pull_changes(remote="origin", branch="main", repository_path="/path/to/repo")  # -> bool

# Push changes
push_changes(remote="origin", branch="feature-branch", repository_path="/path/to/repo")  # -> bool

Repository Management​

from codomyrmex.git_operations import (
    Repository,
    RepositoryManager,
    RepositoryType,
    RepositoryMetadataManager,
    RepositoryMetadata,
    CloneStatus,
)

# Repository types
repo_type = RepositoryType.OWN  # OWN, FORK, USE

# Repository manager (lookup keys use owner/name)
manager = RepositoryManager(metadata_file="/path/to/state/repositories.json")
repo = manager.get_repository("example/repo")

# Metadata persistence
metadata_mgr = RepositoryMetadataManager(
    metadata_file="/path/to/state/repositories.json"
)
metadata = metadata_mgr.get_repository_metadata("example/repo")

Merge Conflict Resolution​

from codomyrmex.git_operations.merge_resolver import MergeResolver, ResolutionStrategy

resolver = MergeResolver(repo_path=Path("/path/to/repo"))

# Detect all conflicts
report = resolver.detect_conflicts()
print(report.files_affected)
print(report.conflicts)

# Resolve a specific file using a strategy
resolver.resolve_file("src/main.py", ResolutionStrategy.OURS)

# Auto-resolve trivial conflicts (whitespace-only differences)
resolved_count = resolver.auto_resolve_trivial()

Available strategies: ResolutionStrategy.OURS, ResolutionStrategy.THEIRS, ResolutionStrategy.UNION, ResolutionStrategy.MANUAL.

PR Automation​

from codomyrmex.git_operations.pr_builder import PRBuilder, PRSpec, FileChange

builder = PRBuilder()
pr = builder.create(
    changes=[FileChange("src/new.py", "def hello(): pass")],
    description="Add hello function",
)
print(pr.branch)    # "auto/add-hello-function"
print(pr.to_dict())

PRBuilder.create() accepts:

  • changes -- list of FileChange objects (path, content, action)
  • description -- PR description
  • title -- PR title (auto-generated from changes if empty)
  • labels -- list of label strings
  • test_results -- dict of test pass/fail summary

Error Handling​

from codomyrmex.exceptions import GitOperationError, RepositoryError

try:
    clone_repository("https://github.com/example/repo.git", "/path/to/local")
except GitOperationError as e:
    print(f"Git command failed: {e.context.get('git_command')}")
except RepositoryError as e:
    print(f"Repository error: {e}")

Configuration​

The module respects Git configuration from:

  1. Repository-level .git/config
  2. User-level ~/.gitconfig
  3. System-level /etc/gitconfig
  4. Environment variables (GIT_AUTHOR_NAME, GIT_AUTHOR_EMAIL, etc.)

Repository metadata persistence is separate from Git configuration. An explicit metadata_file takes precedence. Otherwise the manager uses CODOMYRMEX_REPOSITORY_METADATA_FILE, then $XDG_STATE_HOME/codomyrmex/git_operations/repository_metadata.json, then ~/.local/state/codomyrmex/git_operations/repository_metadata.json. Runtime metadata and timestamped backups are not package resources.

CLI Interface​

# Clone repository
codomyrmex git clone https://github.com/example/repo.git

# Show status
codomyrmex git status

# Create branch
codomyrmex git branch feature/new-feature

# Commit changes
codomyrmex git commit -m "Add feature"

Integration Points​

  • logging_monitoring - All operations are logged
  • exceptions - Uses unified exception hierarchy
  • config_management - Git configuration integration
  • security - Credential management