Git Operations Module - Codomyrmex

Cursor rules for developing the `git_operations` module within Codomyrmex, an ant-inspired modular coding workspace for AI development workflows.

Purpose

This skill provides guidelines for building a Python API that wraps Git CLI operations via subprocess calls. The module enables programmatic, secure, and logged version control interactions to support automation of Git workflows.

Core Principles

1. **Security First**: Never use `shell=True` with subprocess; always pass commands as lists

2. **Structured Output**: Return typed data structures (dicts, lists) rather than raw strings

3. **Comprehensive Error Handling**: Catch exceptions and return typed results (bool/None/empty collections)

4. **Logging**: Track all significant operations via the `logging_monitoring` module

5. **Cross-Platform Compatibility**: Support Windows, Linux, and macOS

Instructions

Module Structure

When working in this module, reference these key files:

Python API Implementation

Follow these standards when implementing Git wrapper functions:

1. **Subprocess Safety**

- Use `subprocess.run()` with command as a list: `subprocess.run(["git", "status"], ...)`

- NEVER use `shell=True` with user input

- Pass all user strings as list elements to prevent command injection

- Use `cwd` parameter instead of changing directories

2. **Error Handling Philosophy**

- Catch subprocess exceptions and return typed results

- Return `False`, `None`, or empty collections on error (not exceptions)

- Log errors via `logging_monitoring` module

- Allow callers to check results without try/except blocks

3. **Function Design**

- Write comprehensive docstrings explaining parameters, return values, behavior

- Return structured data where applicable (not raw Git output)

- Design for idempotency when possible

- Add `@monitor_performance` decorator for operation tracking

4. **Code Style**

- Follow PEP 8 guidelines

- Keep `API_SPECIFICATION.md` as source of truth

- Align all documentation with implemented API

Testing Strategy

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

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

**Security Tests**

Documentation Requirements

Platform Considerations

Logging and Monitoring

Examples

Secure Subprocess Call

```python

def get_status(repo_path: str) -> dict:

"""Get repository status."""

try:

result = subprocess.run(

["git", "status", "--porcelain"],

cwd=repo_path,

capture_output=True,

text=True,

check=True

)

return parse_status_output(result.stdout)

except subprocess.CalledProcessError as e:

logger.error(f"Git status failed: {e}")

return {}

```

Error Handling Pattern

```python

def commit_changes(repo_path: str, message: str) -> bool:

"""Commit staged changes with message."""

try:

subprocess.run(

["git", "commit", "-m", message],

cwd=repo_path,

check=True,

capture_output=True

)

logger.info(f"Committed changes: {message}")

return True

except subprocess.CalledProcessError as e:

logger.error(f"Commit failed: {e.stderr}")

return False

```

Integration Test Pattern

```python

def test_commit_workflow(tmp_path):

"""Test creating branch, committing, and checking status."""

repo = tmp_path / "test_repo"

repo.mkdir()

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

# Create and commit file

(repo / "test.txt").write_text("content")

subprocess.run(["git", "add", "."], cwd=repo)

# Test API

assert commit_changes(str(repo), "Initial commit")

status = get_status(str(repo))

assert status["clean"] == True

```

Important Notes

Constraints