# Version Sync Guide

## Overview
This system helps you manage version synchronization between your dev box (Mac) and production server (GitHub).

## Quick Commands

### Check Version Status
```bash
php scripts/version_sync.php check
```
Shows:
- Current local version
- Current production (GitHub) version  
- Whether you're ahead, behind, or in sync
- List of commits that differ

### Pull Latest from Production
```bash
php scripts/version_sync.php pull
```
Downloads latest commits from GitHub to your local machine.

**Safety Features:**
- Checks for uncommitted changes first
- Shows what will be updated
- Logs all operations to `debug/version_sync.log`
- Reminds you to check for new database migrations

### Rollback to Previous Version
```bash
php scripts/version_sync.php rollback
```
Goes back one commit. Asks for confirmation first.

### Go to Specific Version
```bash
php scripts/version_sync.php goto <commit-hash>
```
Jump to any specific commit. Use short hash (8 chars) or full hash.

Example:
```bash
php scripts/version_sync.php goto 2da92a41
```

## Typical Workflows

### Production Updated, Need to Sync Local
```bash
# 1. Check what's new
php scripts/version_sync.php check

# 2. Pull the updates
php scripts/version_sync.php pull

# 3. Check for new migrations
ls database/migrations/

# 4. Run any new migrations
mysql -u rpmbbu -p brickwal_m1_ds < database/migrations/XXX_name.sql
```

### Local Changes, Need to Push to Production
```bash
# 1. Make sure everything is committed
git status

# 2. Check sync status
php scripts/version_sync.php check

# 3. Push your changes
git push origin main

# 4. On production server, pull updates
php scripts/version_sync.php pull
```

### Something Broke, Need to Rollback
```bash
# Option 1: Go back one commit
php scripts/version_sync.php rollback

# Option 2: Go to specific known-good version
git log --oneline -10  # Find the commit you want
php scripts/version_sync.php goto <hash>
```

## Production Server Setup

When you're on the production server, the same script works:

```bash
# Check if production needs updates
php scripts/version_sync.php check

# Pull latest from GitHub
php scripts/version_sync.php pull
```

## Safety Features

1. **Won't pull if you have uncommitted changes**
   - Commit or stash your work first
   
2. **Confirmation required for destructive operations**
   - Rollback requires typing "yes"
   - Goto specific version requires typing "yes"

3. **Comprehensive logging**
   - All operations logged to `debug/version_sync.log`
   - Check this file if something goes wrong

4. **Git native**
   - Uses standard git commands under the hood
   - You can always use git directly if needed

## Manual Git Commands (Alternative)

If you prefer using git directly:

```bash
# Check status
git fetch origin
git log HEAD..origin/main --oneline  # Behind
git log origin/main..HEAD --oneline  # Ahead

# Pull latest
git pull origin main

# Rollback
git reset --hard HEAD~1

# Go to specific version  
git reset --hard <hash>
```

## Troubleshooting

### "You have uncommitted changes"
```bash
# See what's uncommitted
git status

# Option 1: Commit them
git add .
git commit -m "Your message"

# Option 2: Stash them temporarily
git stash push -m "Temporary stash"
# ... do your pull/rollback ...
git stash pop
```

### "Failed to fetch"
- Check internet connection
- Verify GitHub credentials
- Try: `git fetch origin` manually

### Merge Conflicts After Pull
```bash
# If conflicts occur during pull
git status  # See conflicted files
# Manually edit files to resolve conflicts
git add .
git commit -m "Resolve merge conflicts"
```

### Need to See Full History
```bash
# View recent commits
git log --oneline -20

# View with dates
git log --oneline --date=short --pretty=format:"%h %ad %s" -10
```

## Database Migration Reminder

After pulling updates, ALWAYS check for new migrations:

```bash
# List migrations
ls -la database/migrations/

# Check which you've already run
mysql -u rpmbbu -p brickwal_m1_ds -e "SHOW TABLES"

# Run new migration
mysql -u rpmbbu -p brickwal_m1_ds < database/migrations/030_new_feature.sql
```

## Log File Location

All version sync operations are logged to:
```
debug/version_sync.log
```

Check this file if you need to see what happened during a sync operation.