uniswap_auto_clp/tools/commands/README.md

# Git Agent Slash Commands

This directory contains custom slash commands for the Git Agent system in the Uniswap Auto CLP project. These commands provide easy access to Git operations through OpenCode's interface.

## Available Commands

### `/git-backup`
Creates an automated backup of the current project state.

**Usage:** `/git-backup`

**What it does:**
- Creates a new backup branch with timestamp (format: `backup-YYYY-MM-DD-HH`)
- Commits all current changes with detailed message
- Pushes backup to remote repository
- Cleans up old backups according to retention policy

**Example output:**
```
✅ Backup completed successfully

Automated backup created and pushed to remote repository.
```

### `/git-status`
Shows the current status of the Git Agent system.

**Usage:** `/git-status`

**What it shows:**
- Current branch
- Number of backup branches available
- Whether there are uncommitted changes
- Number of changed files
- Remote repository connection status
- Last backup information

**Example output:**
```
📊 Git Agent Status

   Current Branch: main
   Backup Count: 15
   Has Changes: true
   Changed Files: 3
   Remote Connected: true
   Last Backup: backup-2025-12-19-14

   Recent Backups:
     - backup-2025-12-19-14
     - backup-2025-12-19-13
     - backup-2025-12-19-12
```

### `/git-cleanup`
Cleans up old backup branches according to retention policy.

**Usage:** `/git-cleanup`

**What it does:**
- Removes oldest backup branches when count exceeds limit
- Deletes both local and remote branches
- Keeps the most recent backups (default: 100)

**Example output:**
```
✅ Cleanup completed

Old backup branches have been removed according to retention policy.
```

### `/git-restore [timestamp]`
Restores the project to a previous backup state.

**Usage:** 
- `/git-restore` - Shows available backups
- `/git-restore <timestamp>` - Restores to specific backup

**Timestamp formats:**
- `YYYY-MM-DD-HH` (full timestamp)
- `YYYY-MM-DD` (date only, uses 00:00)
- `MM-DD-HH` (current year assumed)

**Example usage:**
```bash
/git-restore                    # Show available backups
/git-restore 2025-12-19-14     # Restore to Dec 19, 2025 at 14:00
/git-restore 12-19-14          # Restore to current year, Dec 19 at 14:00
```

**Example output (showing backups):**
```
📂 Available Backups

Choose a backup to restore:
• `2025-12-19-14` - 2025-12-19 14:00 UTC
• `2025-12-19-13` - 2025-12-19 13:00 UTC
• `2025-12-19-12` - 2025-12-19 12:00 UTC
• `2025-12-19-11` - 2025-12-19 11:00 UTC

Usage: /git-restore <timestamp> (e.g., 2025-12-19-14)
```

**Example output (successful restore):**
```
✅ Restored to backup

Branch: backup-2025-12-19-14
Time: 2025-12-19 14:00 UTC

⚠️ Note: You're now on a backup branch. Use `git checkout main` to return to the main branch when done.
```

## Technical Details

### Project Structure
```
tools/
├── commands/
│   ├── git_backup.py    # /git-backup implementation
│   ├── git_status.py    # /git-status implementation  
│   ├── git_cleanup.py   # /git-cleanup implementation
│   └── git_restore.py   # /git-restore implementation
├── git_agent.py         # Main Git Agent system
├── agent_config.json    # Configuration file
└── README_GIT_AGENT.md  # Git Agent documentation
```

### Integration with Git Agent

All slash commands use the existing Git Agent system (`git_agent.py`) which provides:
- Automated backup creation
- Backup branch management
- Remote repository synchronization
- Security validation
- Detailed logging

### Configuration

The Git Agent behavior is configured via `tools/agent_config.json`:
- **Backup frequency**: How often to create backups
- **Retention policy**: Maximum number of backups to keep
- **Remote settings**: Gitea repository configuration
- **Security**: Secrets validation and exclusion

### Security Features

- Private keys and tokens are excluded from backups
- Environment variables are handled securely
- Automated security validation for all backups
- Configuration files with sensitive data are ignored

## Usage Workflow

### Daily Development
1. Make changes to your trading bot
2. Use `/git-backup` to create automated backup
3. Continue development or use `/git-status` to check state

### Recovery Scenarios
1. **Rollback bad changes**: Use `/git-restore <timestamp>` to revert
2. **Check project state**: Use `/git-status` for overview
3. **Clean old backups**: Use `/git-cleanup` to maintain storage

### Best Practices
- Backup frequently during major changes
- Use `/git-status` before important operations
- Keep backup names meaningful (timestamps help)
- Test restores after major changes

## Troubleshooting

### Common Issues

**Backup fails:**
- Check if there are any changes to backup
- Verify Git repository is properly initialized
- Check remote repository connection

**Restore fails:**
- Verify backup timestamp exists
- Check if branch is still available
- Ensure you're not in the middle of another operation

**Status shows errors:**
- Check Git repository health
- Verify remote repository access
- Review configuration file

### Getting Help

- Use `/git-status` to diagnose issues
- Check `git_agent.log` for detailed error information
- Review Git Agent documentation in `README_GIT_AGENT.md`

## Future Enhancements

Potential improvements to the slash command system:
- **Scheduled backups**: Auto-backup at regular intervals
- **Backup search**: Search backups by content or metadata
- **Diff viewer**: Compare backups without restoring
- **Batch operations**: Multiple backup operations at once
- **Integration alerts**: Notifications for backup status

## Dependencies

- Python 3.7+
- Git command line tools
- Access to configured remote repository (Gitea)
- Project directory: `K:\Projects\uniswap_auto_clp`

## License

This slash command system is part of the Uniswap Auto CLP project and follows the same licensing terms.