# Backup-Env-Files Safety Guide

## Pre-execution Safety Checklist

### 1. Initial Assessment

```bash
# See what files will be backed up
./backup-env-files.sh --list

# Test what would happen without making changes
./backup-env-files.sh --dry-run
```

### 2. Backup Your Current State (Optional but Recommended)

```bash
# Create a snapshot of your current docker directory
tar -czf ~/docker-backup-$(date +%Y%m%d-%H%M%S).tar.gz ~/docker/
```

### 3. Initialize Safely

```bash
# First time setup
./backup-env-files.sh --init
```

### 4. Regular Backup (Safe)

```bash
# Regular backup operation
./backup-env-files.sh
```

## Data Flow Understanding

### Backup Operation (Safe - No local changes)

```
Source: ~/docker/*/.env files
Target: ~/.env-backup/docker-containers/
Remote: Your Gitea repository
```

### Restore Operation (Caution - Modifies local files)

```
Source: ~/.env-backup/docker-containers/
Target: ~/docker/*/.env files  ⚠️ OVERWRITES LOCAL
```

## File Safety Matrix

| Operation | Local Docker Files | Gitea Repository | Local Backup |
|-----------|-------------------|------------------|--------------|
| `--list` | ✅ Read Only | ❌ No Contact | ❌ No Contact |
| `--dry-run` | ✅ Read Only | ❌ No Contact | ❌ No Contact |
| `--init` | ✅ Read Only | ✅ Creates Repo | ✅ Creates Structure |
| Regular backup | ✅ Read Only | ✅ Updates/Adds Files | ✅ Updates Files |
| `--restore` | ⚠️ OVERWRITES | ✅ Read Only | ✅ Read Only |

## Important Notes

### What WON'T Happen

- ❌ Your docker repository files won't be touched during backup
- ❌ Files won't be deleted from Gitea repository
- ❌ Your working docker-compose.yml files won't be modified

### What WILL Happen

- ✅ .env files will be copied to backup location
- ✅ Changed files will be committed to Gitea
- ✅ Reference docker-compose.yml files may be created (as .ref files)
- ✅ Git history will track all changes

### Restore Function Warnings

- ⚠️ `--restore` WILL overwrite local .env files
- ⚠️ Always prompts for confirmation on conflicts
- ⚠️ Test restore in a safe environment first

## Best Practices

1. **Always test first**: Use `--dry-run` before your first backup
2. **Review file list**: Use `--list` to understand what's being backed up
3. **Version control**: Your Gitea repo will have full Git history
4. **Selective restore**: The script asks for confirmation before overwriting existing files
5. **Monitor logs**: Check `logs/env-backup.log` for detailed operation history

## Emergency Recovery

If something goes wrong:

```bash
# Check Git history in backup repository
cd ~/.env-backup
git log --oneline

# Revert to previous state if needed
git reset --hard HEAD~1

# Or restore from your docker directory snapshot
tar -xzf ~/docker-backup-YYYYMMDD-HHMMSS.tar.gz -C ~/
```