WPHammer
Log in
  • Enabling file backups
  • Incremental vs full
  • Related

    • File Backups

    File backups capture your WordPress site's files — themes, plugins, uploads, and configuration — and upload them to S3-compatible storage. They work alongside database backups as part of the BackupSitePipeline and support incremental mode to reduce transfer time and storage costs.

    What gets backed up

    File backups include:

    • The entire wp-content directory (themes, plugins, uploads, mu-plugins)
    • wp-config.php
    • .htaccess

    The following directories are excluded by default:

    • wp-content/cache
    • wp-content/upgrade
    • wp-content/backup-*
    • wp-content/ai1wm-backups
    • wp-content/updraft

    You can add additional exclusions via the file_excludes array on the BackupConfig.

    How file backups work

    The BackupSitePipeline runs file backups in three stages:

    1. Manifest collection

    The CollectFileManifestJob connects via SSH and generates a SHA256 hash for every file in the backup scope. This produces a BackupFileManifest record with a JSON map of file paths to hashes, plus counts for total_files and changed_files.

    If a previous manifest exists, the ManifestDiffService compares the two to determine what changed and what was deleted. If less than 80% of files have changed, the backup is marked as incremental.

    2. Archive creation

    The CreateFileBackupJob builds the archive via SSH:

    • Full backup — creates a tar.gz of the entire backup scope with the configured exclusions
    • Incremental backup — archives only the changed files identified by the manifest diff, and uploads a deletions.json file listing removed files

    The archive is uploaded to S3 using the AWS CLI on the server. The s3_file_path and file_size_bytes are recorded on the Backup model.

    3. Finalization

    The FinalizeBackupJob checks the outcome. If the file backup is still in Pending status (meaning files were not included in the config), it marks the status as Skipped. A RestorePoint is created for the completed backup. If either the database or file component failed, a BackupFailedNotification is sent.

    Enabling file backups

    File backups are controlled by the include_files flag on BackupConfig. When disabled, only database backups run and the file status is marked as Skipped.

    To configure file backups:

    1. Enable include_files on the site's backup config
    2. Ensure the server has a storage provider assigned with valid credentials
    3. Set any additional file_excludes if your site has directories that should not be backed up (large cache directories, build artifacts, etc.)

    Incremental vs full

    The decision between full and incremental is automatic, based on the ManifestDiffService:

    • Full — when no previous manifest exists, or when 80% or more of files have changed
    • Incremental — when less than 80% of files have changed since the last backup

    Incremental backups are significantly faster for sites with large media libraries where most files remain unchanged between backup runs.

    Related