SCRIPT: Backup-Folder.ps1
LANGUAGE: PowerShell
DIFFICULTY: Intermediate
CATEGORY: Automation
VERSION: 1.0
UPDATED: 2024-12-21

================================================================================
SUMMARY
================================================================================

A PowerShell script that creates timestamped backups of specified folders. Includes options for ZIP compression, detailed logging, and automatic cleanup of old backups based on a configurable retention policy. Ideal for scheduled backup tasks.

================================================================================
WHAT IT DOES
================================================================================

This script performs folder backups with these features:

- Creates timestamped backup copies (format: FolderName_2024-12-21_143052)
- Supports multiple source folders in a single run
- Optional ZIP compression to save disk space
- Detailed logging of all operations with timestamps
- Progress reporting during backup
- Automatic cleanup of old backups based on retention days
- Summary report showing success/failure counts and total size
- Error handling that continues with remaining folders if one fails

================================================================================
HOW TO USE
================================================================================

Simple folder backup:
    .\Backup-Folder.ps1 -SourcePaths "C:\Documents" -DestinationPath "D:\Backups"

Backup multiple folders:
    .\Backup-Folder.ps1 -SourcePaths "C:\Documents","C:\Projects" -DestinationPath "D:\Backups"

Create compressed ZIP backup:
    .\Backup-Folder.ps1 -SourcePaths "C:\Data" -DestinationPath "D:\Backups" -Compress

Keep backups for 7 days only:
    .\Backup-Folder.ps1 -SourcePaths "C:\Data" -DestinationPath "D:\Backups" -RetentionDays 7

Full featured backup:
    .\Backup-Folder.ps1 -SourcePaths "C:\Work","C:\Personal" -DestinationPath "D:\Backups" -Compress -RetentionDays 14 -LogPath "C:\Logs\backup.log"

================================================================================
PARAMETERS
================================================================================

-SourcePaths (Required)
    One or more folder paths to back up. Separate multiple paths with commas.
    Example: -SourcePaths "C:\Documents"
    Example: -SourcePaths "C:\Folder1","C:\Folder2","C:\Folder3"

-DestinationPath (Required)
    The folder where backups will be stored.
    Will be created automatically if it does not exist.
    Example: -DestinationPath "D:\Backups"

-Compress (Optional Switch)
    Creates a ZIP archive instead of copying the folder.
    Saves disk space but takes longer to create.
    Example: -Compress

-RetentionDays (Optional, Default: 30)
    Number of days to keep old backups.
    Backups older than this are automatically deleted.
    Set to 0 to disable automatic cleanup.
    Example: -RetentionDays 7

-LogPath (Optional)
    Path to the log file.
    Default: backup_log.txt in the destination folder.
    Example: -LogPath "C:\Logs\backup.log"

================================================================================
THINGS TO BE CAREFUL OF
================================================================================

1. DISK SPACE: Ensure the destination has enough space for your backups.
   Compressed backups use less space but require temporary space during creation.

2. LONG PATHS: Windows has a 260 character path limit. Deep folder structures
   may cause issues. Consider using shorter destination paths.

3. OPEN FILES: Files that are open or locked by other programs may fail to copy.
   Close applications before backing up their data folders.

4. RETENTION DELETES FILES: The cleanup process permanently deletes old backups.
   Make sure your RetentionDays value is appropriate for your needs.

5. NETWORK DESTINATIONS: Backing up to network drives is slower and may fail
   if the connection is interrupted. Prefer local drives when possible.

6. PERMISSIONS: You need read access to source folders and write access to
   the destination folder. Run as Administrator if needed.

7. TIMESTAMPS: Backup folder names include timestamps. Changing your system
   clock may affect which backups get deleted by the retention policy.

================================================================================
INPUTS
================================================================================

- Source folder paths (files and subfolders within will be backed up)
- Destination path for storing backups
- Optional configuration parameters

================================================================================
OUTPUTS
================================================================================

Folder backup mode:
- Creates: DestinationPath\FolderName_YYYY-MM-DD_HHMMSS\

Compressed backup mode:
- Creates: DestinationPath\FolderName_YYYY-MM-DD_HHMMSS.zip

Log file:
- Creates or appends to: DestinationPath\backup_log.txt (or custom LogPath)

Console output:
- Progress updates with timestamps
- Color-coded status messages (Info, Warning, Error, Success)
- Summary report at completion

Exit codes:
- 0: All backups completed successfully
- 1: One or more backups failed

================================================================================
SCHEDULING AUTOMATIC BACKUPS
================================================================================

You can use Windows Task Scheduler to run this script automatically:

# Create a daily backup task at 2 AM
$action = New-ScheduledTaskAction -Execute "PowerShell.exe" -Argument "-ExecutionPolicy Bypass -File C:\Scripts\Backup-Folder.ps1 -SourcePaths 'C:\Documents' -DestinationPath 'D:\Backups' -Compress"
$trigger = New-ScheduledTaskTrigger -Daily -At "2:00AM"
$settings = New-ScheduledTaskSettingsSet -StartWhenAvailable
Register-ScheduledTask -TaskName "Daily Backup" -Action $action -Trigger $trigger -Settings $settings

================================================================================
REQUIREMENTS
================================================================================

- Windows PowerShell 5.1 or higher
- Windows operating system
- Compress-Archive cmdlet (included in PowerShell 5.0+)
- No external modules required

================================================================================
EXAMPLE LOG OUTPUT
================================================================================

[2024-12-21 14:30:00] [Info] ==================================================
[2024-12-21 14:30:00] [Info] BACKUP OPERATION STARTED
[2024-12-21 14:30:00] [Info] Timestamp: 2024-12-21_143000
[2024-12-21 14:30:00] [Info] ==================================================
[2024-12-21 14:30:00] [Info] Processing: C:\Documents
[2024-12-21 14:30:01] [Info] Creating compressed backup: D:\Backups\Documents_2024-12-21_143000.zip
[2024-12-21 14:30:15] [Success] Compressed backup created: 45.2 MB
[2024-12-21 14:30:15] [Info] Checking for backups older than 30 days...
[2024-12-21 14:30:15] [Info] No old backups to remove
[2024-12-21 14:30:15] [Info] ==================================================
[2024-12-21 14:30:15] [Info] BACKUP SUMMARY
[2024-12-21 14:30:15] [Success] Successful: 1