tkb_timeshift/AUTO-COMMIT-README.md

# Auto-Commit System for Timeshift Project

This system automatically saves your work to git to prevent losing changes when Claude gets restarted or when making experimental changes.

## 🚀 Quick Start

### Start Auto-Watch (Recommended)
```bash
npm run watch-commit
```
This will automatically commit changes every 30 seconds when files are modified.

### Manual Commands
```bash
# Save current work immediately
npm run save "Your commit message"

# Create a restore point before major changes
npm run restore-point "Before major refactor"

# List all restore points
./auto-commit.sh list

# Clean old restore points (keeps last 10)
./auto-commit.sh cleanup
```

## 📋 How It Works

### Automatic Commits
- **File Watcher**: Monitors `components/`, `app/`, `lib/`, `styles/` directories
- **Smart Delay**: Waits 30 seconds after last change before committing
- **Rate Limiting**: Max 10 commits per hour to avoid spam
- **File Types**: Watches `.tsx`, `.ts`, `.js`, `.jsx`, `.css`, `.scss`, `.json` files

### Restore Points
- **Branches**: Creates timestamped branches like `restore-point-20250129-143022`
- **Automatic**: Creates restore points on startup and every 30 minutes
- **Manual**: Create before risky changes with `npm run restore-point "description"`

## 🔧 Features

### Auto-Commit Script Features
✅ Automatic timestamped commits  
✅ Descriptive commit messages  
✅ Rate limiting to prevent spam  
✅ Restore point creation  
✅ Cleanup of old restore points  
✅ Git status checking  

### File Watcher Features  
✅ Real-time file monitoring  
✅ Smart batching of changes  
✅ Graceful shutdown handling  
✅ Periodic restore points  
✅ Console logging for transparency  

## 📚 Usage Examples

### Starting Your Work Session
```bash
# Start the auto-commit watcher
npm run watch-commit

# In another terminal, start development
npm run dev
```

### Before Making Risky Changes
```bash
# Create a restore point
npm run restore-point "Before implementing new feature"

# Make your changes...
# Files are auto-committed as you work

# If something breaks, restore with:
git checkout restore-point-20250129-143022
```

### Manual Saves
```bash
# Quick save
npm run save

# Save with custom message
npm run save "Fixed spreadsheet column alignment"
```

### Managing Restore Points
```bash
# List all restore points
./auto-commit.sh list

# Clean up old ones (keeps last 10)
./auto-commit.sh cleanup
```

## 🎯 Benefits

1. **Never Lose Work**: Changes are saved every 30 seconds automatically
2. **Easy Recovery**: Restore points let you go back to working states
3. **Experiment Safely**: Try changes knowing you can always revert
4. **Claude Restarts**: No more losing progress when Claude session ends
5. **Version History**: Full git history of all changes with timestamps

## ⚙️ Configuration

### Modify Watch Settings
Edit `watch-and-commit.js`:
```javascript
const COMMIT_DELAY = 30000; // 30 seconds
const MAX_COMMITS_PER_HOUR = 10;
const WATCH_DIRS = ['components', 'app', 'lib', 'styles'];
```

### Modify Auto-Commit Behavior
Edit `auto-commit.sh` to change commit message format or add custom logic.

## 🛟 Recovery Scenarios

### Claude Gets Restarted
Your work is automatically saved! Just continue from where you left off.

### Experimental Changes Break Things
```bash
# List restore points to find a good one
./auto-commit.sh list

# Checkout the restore point
git checkout restore-point-20250129-143022

# Or continue from main with your auto-commits
git checkout main
git log --oneline -10  # See recent auto-commits
```

### Need to Go Back a Few Commits
```bash
# See recent commits
git log --oneline -10

# Reset to a specific commit (keep files)
git reset --soft HEAD~3

# Or create a new branch from specific commit
git checkout -b fix-attempt abc1234
```

## 🚦 Status Indicators

The watcher shows:
- 🔍 **Started**: Auto-commit watcher is running
- 📝 **File changed**: A file was modified
- 🔄 **Performing auto-commit**: About to save changes
- ✅ **Auto-commit successful**: Changes saved
- 🔖 **Creating restore point**: Making a backup branch
- ⏸️ **Rate limit reached**: Too many commits, pausing

## 🎮 Quick Reference

| Command | Purpose |
|---------|---------|
| `npm run watch-commit` | Start automatic file watching |
| `npm run save` | Immediate manual commit |
| `npm run restore-point` | Create backup branch |
| `./auto-commit.sh list` | Show restore points |
| `./auto-commit.sh cleanup` | Remove old restore points |
| `git checkout restore-point-XXXXXX` | Restore to backup |
| `git log --oneline -10` | See recent commits |

---

**Pro Tip**: Always run `npm run watch-commit` when starting work with Claude to ensure nothing gets lost! 🛡️