# Quick Start Guide: Security-Focused CWD Operations
## For Users
### What's Changed?
**BREAKING CHANGE**: For security reasons, all operations now work ONLY on the current working directory:
- ❌ No more `repo_path` parameters
- ❌ No more `COMMITIZEN_REPO_PATH` environment variable
- ✅ You must `cd` to your repository before running commands
### Basic Usage
```bash
# Old way (v1.x) - NO LONGER WORKS
commit_helper get_git_status --repo-path /path/to/repo
# New way (v2.0) - REQUIRED
cd /path/to/repo
commit_helper get_git_status
```
### Quick Migration
1. **Remove all `repo_path` parameters**
2. **Remove `COMMITIZEN_REPO_PATH` from your environment**
3. **Add `cd` commands before operations**
### Example Workflow
```bash
# Navigate to your repository
cd ~/projects/my-repo
# All commands now work on current directory
commit_helper get_git_status
commit_helper generate_commit_message --type feat --subject "Add new feature"
commit_helper validate_commit_message --message "feat: Add new feature"
```
## For Developers
### 1. Updating Your Code (2 minutes)
Remove all `repo_path` parameters from your code:
```python
# ❌ OLD - This will fail
result = commit_helper.get_git_status(repo_path="/some/path")
# ✅ NEW - Change directory first
import os
os.chdir("/some/path")
result = commit_helper.get_git_status()
```
### 2. Updating Scripts (3 minutes)
Update your shell scripts:
```bash
#!/bin/bash
# ❌ OLD SCRIPT
commit_helper analyze_repository_health --repo-path /repo1
commit_helper analyze_repository_health --repo-path /repo2
# ✅ NEW SCRIPT
cd /repo1 && commit_helper analyze_repository_health
cd /repo2 && commit_helper analyze_repository_health
```
### 3. Multi-Repository Helper (5 minutes)
Create a helper function for multi-repository operations:
```python
from contextlib import contextmanager
import os
@contextmanager
def in_repository(repo_path):
"""Context manager for repository operations."""
original = os.getcwd()
try:
os.chdir(repo_path)
yield
finally:
os.chdir(original)
# Usage
repos = ["/repo1", "/repo2", "/repo3"]
for repo in repos:
with in_repository(repo):
result = commit_helper.get_git_status()
print(f"{repo}: {result}")
```
## Common Patterns
### Pattern 1: Single Repository
```python
# Simple - just ensure you're in the right directory
os.chdir("/path/to/repo")
result = commit_helper.generate_commit_message(
type="feat",
subject="Add new feature"
)
```
### Pattern 2: Multiple Repositories
```python
def process_repositories(repo_paths):
"""Process multiple repositories."""
original_dir = os.getcwd()
results = {}
try:
for repo_path in repo_paths:
os.chdir(repo_path)
results[repo_path] = commit_helper.get_git_status()
finally:
os.chdir(original_dir)
return results
```
### Pattern 3: CI/CD Integration
```yaml
# GitHub Actions
- name: Generate commit message
working-directory: ${{ github.workspace }}
run: |
commit_helper generate_commit_message \
--type feat \
--subject "Automated update"
# GitLab CI
generate_commit:
script:
- cd $CI_PROJECT_DIR
- commit_helper generate_commit_message --type feat --subject "Update"
```
## Error Handling
### Common Errors and Solutions
| Error | Solution |
|-------|----------|
| `TypeError: got an unexpected keyword argument 'repo_path'` | Remove the `repo_path` parameter |
| `Current directory is not a git repository` | `cd` to a git repository first |
| `No read access to current working directory` | Check directory permissions |
### Quick Validation
Before running operations, validate your setup:
```bash
# Check current directory
pwd
# Verify it's a git repository
git status
# Test commit helper
commit_helper get_git_status
```
## Installation Options
### Recommended: Dev Dependency Approach
Add commit-helper-mcp as a development dependency to your project:
```toml
# In pyproject.toml
[project.optional-dependencies]
dev = [
"commit-helper-mcp>=0.7.0",
]
```
Install and configure:
```bash
# Install dev dependencies
uv pip install -e ".[dev]"
# Configure MCP server (in Claude/Cline config)
{
"mcpServers": {
"commit-helper-mcp": {
"command": "uv",
"args": ["run", "python", "-m", "commit_helper_mcp.main"]
}
}
}
```
This approach ensures proper git repository access while maintaining security.
## Migration Checklist
- [ ] Remove all `repo_path` parameters from code
- [ ] Remove `COMMITIZEN_REPO_PATH` from environment
- [ ] Update all scripts to use `cd` commands
- [ ] Update CI/CD pipelines
- [ ] Add as dev dependency to projects (recommended)
- [ ] Update MCP server configuration
- [ ] Test all workflows
- [ ] Update documentation
## Why This Change?
### Security Benefits
- **No Path Traversal**: Cannot access `../../../etc/passwd`
- **No Directory Hijacking**: Cannot be tricked into wrong directory
- **Clear Audit Trail**: All directory changes are explicit
### Simplicity Benefits
- **Less Code**: ~30% reduction in codebase
- **Faster Operations**: No path resolution overhead
- **Clearer Errors**: Always about current directory
## Need Help?
### Quick Debugging
```bash
# Where am I?
pwd
# Is this a git repo?
ls -la .git
# What's the error?
commit_helper get_git_status
```
### Resources
- [FAQ & Troubleshooting](./10-faq-troubleshooting.md)
- [Code Examples](./09-code-examples.md)
- [Migration Guide](./MIGRATION_v2.md)
## Summary
The new security-focused approach is simple:
1. **Navigate**: `cd /path/to/repo`
2. **Execute**: `commit_helper <command>`
3. **No Parameters**: No `repo_path` needed
While this requires updating existing code, the security and simplicity benefits make it worthwhile. The explicit directory navigation makes it always clear which repository you're operating on.
