Codomyrmex Git Operations Module

A specialized Cursor rules configuration for the `git_operations` module within the Codomyrmex project—an ant-inspired modular workspace for AI development workflows.

Purpose

Provides a Python API for programmatic Git operations, abstracting direct CLI calls to promote consistent, secure, and logged version control interactions. Supports automation of Git workflows across multiple languages with GitHub integration, repository management, and visualization capabilities.

Key Technologies

Instructions for AI Agent

1. Context Awareness

When working in the `git_operations` module, you MUST supplement these rules with `general.cursorrules` from the project root unless explicitly overridden here.

**Key reference files:**

2. Python Implementation Standards

#### Subprocess Security (CRITICAL)

All Git operations use `subprocess.run()` with **strict security requirements**:

```python

✅ CORRECT: List arguments, no shell

subprocess.run(["git", "status"], cwd=repo_path, capture_output=True)

❌ WRONG: Never use shell=True with user input

subprocess.run(f"git {user_input}", shell=True) # NEVER DO THIS

```

**Mandatory practices:**

#### Error Handling Philosophy

Functions return typed failure values rather than raising exceptions:

```python

def get_status(repo_path: str) -> dict | None:

"""Returns dict on success, None on error."""

try:

result = subprocess.run(["git", "status", "--porcelain"], ...)

if result.returncode != 0:

log_error("Git status failed", repo_path)

return None

return parse_status(result.stdout)

except Exception as e:

log_error("Unexpected error", e)

return None

```

**Return value patterns:**

Callers must check return values rather than relying on try/except.

#### Code Quality Requirements

1. **Structured Output**: Return dictionaries/lists rather than raw Git command strings

2. **Comprehensive Logging**: Use `logging_monitoring` module for all operations

- Log operation name, parameters (excluding credentials), success/failure

3. **Docstrings**: All public API functions must have complete docstrings matching `API_SPECIFICATION.md`

4. **Idempotency**: Design functions to be idempotent where Git supports it

5. **Performance Monitoring**: Apply `@monitor_performance` decorator when available

3. Module Structure

**Core components:**

4. Testing Strategy

#### Unit Tests (`tests/unit/`)

```python

@patch('subprocess.run')

def test_get_status_success(mock_run):

mock_run.return_value = Mock(returncode=0, stdout="M file.py\n")

result = get_status("/repo")

assert result is not None

assert "file.py" in result["modified"]

```

#### Integration Tests (`tests/integration/`)

```python

def test_commit_workflow():

with tempfile.TemporaryDirectory() as tmpdir:

subprocess.run(["git", "init"], cwd=tmpdir)

# Test API calls with real Git repo

assert create_branch(tmpdir, "feature")

assert commit_changes(tmpdir, "Test commit")

```

5. Security Priorities

Reference `SECURITY.md` frequently. Key principles:

1. **Subprocess safety** - List arguments only, no shell=True

2. **Credential handling** - Never log credentials, use Git credential helpers

3. **Input validation** - Sanitize all user inputs before subprocess calls

4. **Cross-platform** - Test path handling on Windows/Linux/macOS

5. **Audit trail** - Log all Git operations via `logging_monitoring`

6. Documentation Maintenance

7. Implementation Checklist

Before completing any feature:

Example Usage

```python

from git_manager import get_status, commit_changes, create_branch

Check repository status

status = get_status("/path/to/repo")

if status:

print(f"Modified files: {status['modified']}")

Create and switch to branch

if create_branch("/path/to/repo", "feature-x"):

print("Branch created successfully")

Commit changes

if commit_changes("/path/to/repo", "Add new feature"):

print("Changes committed")

```

Constraints