# History Manipulation Tools Specification
This document specifies MCP tools for git history manipulation operations, with a focus on safety and user control.
## Tool: rewrite_history_between_tags
### Purpose
Safely remove or modify commits between two tags while preserving the rest of the history and updating tag positions.
### Parameters
```yaml
parameters:
repo_path:
type: string
required: false
description: Path to git repository (defaults to current directory)
start_tag:
type: string
required: true
description: The tag marking the start of the range (exclusive)
end_tag:
type: string
required: true
description: The tag marking the end of the range (inclusive)
commits_to_remove:
type: array[string]
required: false
description: Specific commit hashes to remove (if not provided, interactive mode)
preserve_merges:
type: boolean
default: true
description: Whether to preserve merge commits during rebase
create_backup:
type: boolean
default: true
description: Create a backup branch before rewriting
backup_prefix:
type: string
default: "backup-rewrite"
description: Prefix for backup branch name
update_tags:
type: boolean
default: true
description: Automatically update affected tags to new positions
force_execute:
type: boolean
default: false
description: Actually execute the rewrite (safety flag)
```
### Workflow
```yaml
workflow:
preview_phase:
1. Validate repository and tags exist
2. Check for uncommitted changes
3. Analyze commits between tags
4. Identify dependent tags and branches
5. Calculate impact of removal
6. Generate preview report
execution_phase:
1. Create backup branch if requested
2. Start interactive rebase from start_tag^
3. Apply commit removal/modification
4. Handle any conflicts with guidance
5. Update end_tag to new position
6. Update any dependent tags
7. Generate summary report
rollback_phase:
1. Provide rollback instructions
2. Keep backup branch for recovery
3. Document changes made
```
### Response Format
```json
{
"success": true,
"executed": false, // or true if force_execute
"preview": {
"commits_between_tags": [
{
"hash": "abc1234",
"message": "feat: add feature X",
"author": "John Doe",
"date": "2024-01-15T10:30:00Z",
"will_be_removed": true
}
],
"total_commits": 10,
"commits_to_remove": 3,
"affected_tags": ["v1.2.1", "v1.2.2"],
"affected_branches": ["feature/x"],
"backup_branch": "backup-rewrite-20240115-103000"
},
"execution_result": {
"backup_created": "backup-rewrite-20240115-103000",
"commits_removed": 3,
"new_end_tag_commit": "def5678",
"tags_updated": ["end_tag", "v1.2.2"],
"conflicts_resolved": 0,
"warnings": []
},
"rollback_instructions": [
"git checkout main",
"git reset --hard backup-rewrite-20240115-103000",
"git tag -f end_tag <original-commit>"
]
}
```
### Safety Features
- Preview mode by default
- Automatic backup creation
- Conflict detection and resolution guidance
- Tag dependency analysis
- Remote synchronization warnings
- Comprehensive rollback instructions
### Example Usage
```python
# Preview the operation
result = rewrite_history_between_tags(
start_tag="v1.0.0",
end_tag="v1.1.0",
commits_to_remove=["abc1234", "def5678"]
)
# Execute after review
if user_approves(result["preview"]):
result = rewrite_history_between_tags(
start_tag="v1.0.0",
end_tag="v1.1.0",
commits_to_remove=["abc1234", "def5678"],
force_execute=True
)
```
## Tool: interactive_rebase_helper
### Purpose
Guide users through complex interactive rebase operations with safety checks and automation.
### Parameters
```yaml
parameters:
repo_path:
type: string
required: false
description: Path to git repository
base_ref:
type: string
required: true
description: Base reference for rebase (commit, branch, or tag)
operations:
type: array[object]
required: false
description: Predefined operations to perform
schema:
- commit: string (commit hash)
action: enum["pick", "reword", "edit", "squash", "fixup", "drop"]
message: string (optional, for reword)
auto_squash:
type: boolean
default: false
description: Enable autosquash for fixup/squash commits
preserve_merges:
type: boolean
default: false
description: Preserve merge commits (--rebase-merges)
exec_commands:
type: array[string]
required: false
description: Commands to execute after each commit
force_execute:
type: boolean
default: false
description: Actually execute the rebase
```
### Workflow
```yaml
workflow:
analysis:
1. Analyze commits from base_ref to HEAD
2. Detect fixup/squash commits if auto_squash
3. Validate proposed operations
4. Check for potential conflicts
preview:
1. Show current commit list
2. Show proposed changes
3. Highlight potential issues
4. Estimate conflict likelihood
execution:
1. Start interactive rebase
2. Apply operations automatically
3. Pause for user on conflicts
4. Run exec commands if specified
5. Complete rebase
```
### Response Format
```json
{
"success": true,
"preview": {
"current_commits": [...],
"proposed_sequence": [...],
"potential_conflicts": [...],
"warnings": [...]
},
"execution_result": {
"commits_processed": 10,
"conflicts_encountered": 2,
"final_head": "abc1234",
"exec_results": [...]
}
}
```
## Tool: history_cleanup_tool
### Purpose
Clean up repository history by removing large files, fixing commit messages, or reorganizing commits.
### Parameters
```yaml
parameters:
repo_path:
type: string
required: false
cleanup_type:
type: enum
required: true
values: ["large_files", "author_info", "commit_messages", "empty_commits"]
description: Type of cleanup to perform
cleanup_config:
type: object
required: true
description: Configuration specific to cleanup type
examples:
large_files:
size_threshold: "10MB"
file_patterns: ["*.zip", "*.tar.gz"]
author_info:
old_email: "old@example.com"
new_email: "new@example.com"
new_name: "Correct Name"
commit_messages:
pattern: "regex pattern"
replacement: "replacement text"
affected_refs:
type: array[string]
default: ["HEAD"]
description: Branches/tags to clean
create_backup:
type: boolean
default: true
force_execute:
type: boolean
default: false
```
### Workflow
```yaml
workflow:
analysis:
1. Scan history for cleanup targets
2. Calculate impact and size reduction
3. Identify affected commits
4. Check for protected branches
preview:
1. List items to be cleaned
2. Show before/after comparison
3. Estimate time and resources
4. Warn about downstream impacts
execution:
1. Create backup if requested
2. Perform cleanup operation
3. Update refs
4. Run garbage collection
5. Provide recovery instructions
```
### Response Format
```json
{
"success": true,
"cleanup_summary": {
"type": "large_files",
"files_removed": 15,
"size_reduced": "500MB",
"commits_rewritten": 100,
"time_taken": "45s"
},
"details": [...],
"recovery": {
"backup_ref": "refs/original/refs/heads/main",
"restore_command": "git reset --hard refs/original/refs/heads/main"
}
}
```
## Tool: commit_split_helper
### Purpose
Help split a single commit into multiple logical commits.
### Parameters
```yaml
parameters:
repo_path:
type: string
required: false
commit_ref:
type: string
required: true
description: Commit to split
split_strategy:
type: enum
values: ["by_file", "by_hunk", "interactive"]
default: "interactive"
file_groups:
type: array[object]
required: false
description: Predefined file groupings for split
schema:
- files: array[string]
message: string
force_execute:
type: boolean
default: false
```
### Response Format
```json
{
"success": true,
"original_commit": {
"hash": "abc1234",
"message": "Original commit message",
"files_changed": 10
},
"proposed_splits": [
{
"files": ["src/feature.js", "src/feature.test.js"],
"suggested_message": "feat: add new feature",
"changes": "+50 -10"
},
{
"files": ["docs/README.md"],
"suggested_message": "docs: update documentation",
"changes": "+20 -5"
}
],
"execution_result": {
"new_commits": ["def5678", "ghi9012"],
"success": true
}
}
```
## Tool: history_verification_tool
### Purpose
Verify history integrity after rewrite operations.
### Parameters
```yaml
parameters:
repo_path:
type: string
required: false
verification_checks:
type: array[enum]
default: ["all"]
values: ["commits", "tags", "branches", "remotes", "hooks"]
compare_with:
type: string
required: false
description: Reference to compare against (e.g., backup branch)
deep_check:
type: boolean
default: false
description: Perform deep object verification
```
### Response Format
```json
{
"success": true,
"verification_results": {
"commits": {
"total": 1000,
"verified": 1000,
"issues": []
},
"tags": {
"total": 50,
"verified": 50,
"moved": 5,
"issues": []
},
"branches": {
"total": 10,
"verified": 10,
"diverged": 2,
"issues": []
},
"integrity": {
"objects_valid": true,
"references_valid": true,
"no_dangling_commits": true
}
},
"recommendations": [
"Run 'git gc' to clean up objects",
"Update remote branches with --force-with-lease"
]
}
```
## Common Safety Patterns
All history manipulation tools follow these patterns:
1. **Preview First**: Default behavior shows what will happen
2. **Explicit Execution**: Require `force_execute=True` for changes
3. **Automatic Backups**: Create recovery points before operations
4. **Conflict Handling**: Provide guidance for conflict resolution
5. **Verification**: Post-operation integrity checks
6. **Recovery Path**: Clear instructions for undoing changes
## Integration with Existing Tools
These tools complement existing Commit Helper MCP tools:
- Use after `generate_commit_message` to fix commit messages
- Combine with `get_git_status` to verify state
- Work with `analyze_repository_health` for cleanup decisions
- Integrate with `smart_commit_suggestion` for better commits
## Error Handling
All tools implement comprehensive error handling:
```python
try:
# Perform operation
except GitCommandError as e:
return {
"success": False,
"error": "Git command failed",
"details": str(e),
"recovery_suggestions": [...]
}
except InvalidRepositoryError as e:
return {
"success": False,
"error": "Invalid repository",
"details": str(e),
"suggestions": ["Check repository path", "Initialize git repository"]
}
```
## Future Enhancements
1. **AI-Powered Suggestions**
- Suggest optimal commit groupings
- Recommend squash candidates
- Identify problematic commits
2. **Batch Operations**
- Process multiple repositories
- Apply same cleanup to many branches
- Parallel execution for performance
3. **Advanced Strategies**
- Three-way rebase handling
- Octopus merge preservation
- Submodule history rewriting
4. **Integration Features**
- CI/CD pipeline integration
- Pre-receive hook validation
- Automated history policies
