Cursor Rules for the git_operations Module

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.

5. Documentation (Meta-Documentation for this Module)

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.

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

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.

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.

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.

Cursor Rules for the git_operations Module

Cursor Rules for the git_operations Module

0. Preamble

1. Module Purpose & Context

2. Key Files & Structure

3. Coding Standards & Practices

For Python API (
`git_manager.py`
, etc.):

For Documentation (Markdown):

4. Testing

5. Documentation (Meta-Documentation for this Module)

6. Specific Considerations for
`git_operations`

7. Final Check (when implementing features)

Related Skills

Markdown Converter

Nano Banana Pro

1password

Cursor Rules for the git_operations Module

0. Preamble

1. Module Purpose & Context

2. Key Files & Structure

3. Coding Standards & Practices

For Python API (
`git_manager.py`
, etc.):

For Documentation (Markdown):

4. Testing

5. Documentation (Meta-Documentation for this Module)

6. Specific Considerations for
`git_operations`

7. Final Check (when implementing features)