Cursor Rules for the git_operations Module
0. Preamble
These rules are specific to the git_operations module and supplement general.cursorrules. Always adhere to general.cursorrules unless explicitly overridden here.
1. Module Purpose & Context
- Core Functionality: Provides a Python API for programmatic Git operations, abstracting direct CLI calls and promoting consistent, secure, and logged version control interactions. Aims to support automation of Git workflows within Codomyrmex.
- Key Technologies/Tools: Python,
git CLI via subprocess module.
- Refer to this module's
README.md for a comprehensive overview of its intended scope and design.
2. Key Files & Structure
When working within this module, pay close attention to:
README.md: Comprehensive module overview, quick start guide, and feature list.API_SPECIFICATION.md: Defines the public Python API for Git functions (e.g., get_status, commit_changes). This is the primary contract for users of the module.COMPLETE_API_DOCUMENTATION.md: Detailed documentation with examples for all functions.MCP_TOOL_SPECIFICATION.md: (Currently N/A) Would define any MCP tools for AI-driven Git operations.SECURITY.md: Critical security considerations for automating Git operations, especially credential handling and command execution.USAGE_EXAMPLES.md and COMPREHENSIVE_USAGE_EXAMPLES.md: Examples of how to use the Python API.git_manager.py: Core Python functions wrapping Git commands via subprocess.github_api.py: GitHub API integration for repository and PR management.repository_manager.py: Repository library management and bulk operations.repository_metadata.py: Metadata tracking system for repositories.visualization_integration.py: Optional visualization features (requires data_visualization module).docs/technical_overview.md: In-depth technical design of the Git interaction logic.docs/tutorials/: How-to guides for using the module's API for specific project workflows.
3. Coding Standards & Practices
For Python API (git_manager.py, etc.):
- Follow Python PEP 8 guidelines.
- Subprocess Implementation: The module uses
subprocess.run() for all Git operations. This is the current implementation approach.
- Always pass commands and arguments as a list (e.g.,
subprocess.run(["git", "status"], ...)).
- Never use
shell=True with user-supplied input.
- All user-provided strings are passed as list elements, preventing command injection.
- Use
cwd parameter to specify repository path rather than changing directories.
- Comprehensive Error Handling: Catch exceptions from
subprocess and return typed results (bool, None, empty dict/list) rather than raising exceptions. Errors are logged via logging_monitoring module.
- Structured Output: Return structured data (dictionaries, lists) rather than raw string output from Git commands where applicable.
- Logging: Integrate with the
logging_monitoring module to log all significant Git operations, their parameters (excluding sensitive ones), and their success/failure status.
- Clear Docstrings: All public API functions must have comprehensive docstrings explaining parameters, return values, and behavior, consistent with
API_SPECIFICATION.md.
- Idempotency where applicable: Design functions to be idempotent if the underlying Git command supports it and it makes sense for the use case.
- Performance Monitoring: Use
@monitor_performance decorator from performance module when available for tracking operation latency.
For Documentation (Markdown):
- Ensure
API_SPECIFICATION.md is the source of truth for the Python API.
- Keep tutorials and usage examples aligned with the implemented API.
- Clearly document security implications and prerequisites (like Git authentication setup) for using the API.
4. Testing
- Unit Tests (
tests/unit/):
- Focus on the logic within wrapper functions (argument parsing, subprocess calls, output parsing).
- Mock
subprocess.run() calls to simulate various Git responses (success, errors, different repository states).
- Test error handling and return value types.
- Integration Tests (
tests/integration/):
- These tests should interact with actual (temporary, locally created) Git repositories.
- Create a temporary directory, initialize a Git repo (
git init).
- Perform sequences of API calls (e.g.,
create_branch, commit_changes, get_status) and then assert the state of the local Git repository.
- Clean up temporary repositories after tests.
- These tests will be slower and should be marked appropriately if needed.
- Security: Consider tests that try to misuse API functions with unusual inputs to verify subprocess safety.
- Keep this module's
README.md and docs/technical_overview.md accurately reflecting the design and implementation of the Git automation tools.
6. Specific Considerations for git_operations
- Cross-Platform Compatibility: Be mindful of how Git behaves on different OS (Windows, Linux, macOS), especially regarding paths, line endings, and credential helpers. The subprocess approach works across platforms.
- Security is Paramount: Given that this module interacts with source code and potentially credentials, all design and implementation choices must prioritize security. Refer to
SECURITY.md frequently.
- User Experience for API Consumers: Design the Python API to be intuitive and easy to use correctly.
- Error Handling Philosophy: Functions return False/None/empty collections on error rather than raising exceptions. This allows callers to check results without try/except blocks, but requires careful checking of return values.
7. Final Check (when implementing features)
- Verify that API functions behave as described in
API_SPECIFICATION.md.
- Ensure all operations are logged appropriately via
logging_monitoring.
- Confirm that error handling is robust and user-friendly.
- Update this module's
CHANGELOG.md for any changes to the API or significant functionality.
- Ensure subprocess calls use list arguments and never shell=True.