Skip to main content

Backup File Specification

This page documents FolderRewind backup naming and storage conventions, and how they relate to the Rebuild History feature.

Filename format​

In source code, backup filenames are generated by GenerateFileName(...) in this format:

[Full/Smart/Overwrite][timestamp]folder-name [comment].extension

Examples:

  • [Full][2026-03-01_09-30-15]WorldA.7z
  • [Smart][2026-03-01_10-00-10]WorldA [Auto].7z
  • [Overwrite][2026-03-01_11-22-08]WorldA [Manual].zip

Field definition​

  • Type prefix: [Full], [Smart], [Overwrite]
  • Timestamp: yyyy-MM-dd_HH-mm-ss
  • Folder name: display name of the managed folder
  • Comment: optional, written as [comment]
  • Extension: archive format, typically 7z or zip

Naming notes​

  • Comments are sanitized before writing to file names.
  • [ and ] are removed from comments to avoid parsing conflicts.
  • Avoid manually renaming generated backup files if you want stable history rebuilding.

Source code parsing regex​

HistoryService uses the following regex to parse backup filenames:

^\[(Full|Smart|Overwrite)\]\[(\d{4}-\d{2}-\d{2}_\d{2}-\d{2}-\d{2})\](.+?)(?:\s\[(.+?)\])?\.(7z|zip)$

This means:

  • The type prefix must be one of [Full], [Smart], or [Overwrite]
  • The timestamp format is strictly yyyy-MM-dd_HH-mm-ss
  • The comment part is optional; if present, it is wrapped in square brackets
  • The extension must be 7z or zip

Backup storage structure​

Each config uses its DestinationPath as the backup root and stores archives by managed folder name.

DestinationPath/
├─ <FolderDisplayName>/
│  ├─ [Full][...].7z
│  ├─ [Smart][...].7z
│  └─ [Overwrite][...].zip
└─ _metadata/
   └─ <FolderDisplayName>/
      └─ metadata.json

Backup directory structure example

Notes:

  • DestinationPath/<FolderDisplayName>/: actual backup archive directory.
  • DestinationPath/_metadata/<FolderDisplayName>/metadata.json: smart-incremental chain metadata.

metadata.json version​

The current version is v3.0 (BackupMetadataState), which contains:

  • FileStates: a dictionary recording each file's Size, LastWriteTimeUtc, and Hash
  • BackupRecords: a list of backup records, each containing the added/modified/deleted file list for that backup

Smart incremental backups rely on this file to determine which files have changed.

Default destination path​

If you do not customize destination path, the recommended default root is:

Documents/FolderRewind-Backup

Per config, default destination is usually:

Documents/FolderRewind-Backup/<config-name>

Relationship to Rebuild History​

Rebuild History depends on existing backup files. For more accurate rebuild results:

  1. Keep the naming format (especially type prefix and timestamp).
  2. Keep directory layout as DestinationPath/<FolderDisplayName>/.
  3. Do not arbitrarily delete/rename key files in an incremental chain (especially Full baseline files).

Important flag and auto-pruning​

  • History items can be marked as Important.
  • Auto-pruning skips backup files marked as important.

So for long-term retention, mark milestone backups as important.

Auto-cleanup and safe delete​

When Keep latest backup count (KeepCount) is set to a value greater than 0, the system automatically cleans up old backups that exceed the limit after each backup.

Cleanup behavior interacts with Safe Delete (SafeDeleteEnabled):

  • Safe Delete off: old backup files and their history entries are deleted directly.
  • Safe Delete on: if the backup to be deleted is part of a smart incremental chain, the system first merges its content into the successor backup before deleting, avoiding chain breakage that would make subsequent backups unrestorable.

Recommendation: keep Safe Delete enabled for configs using smart incremental mode.

v1.4.2 adds MARK_IMPORTANT for marking/unmarking important backups:

MARK_IMPORTANT <config_id> <folder_index|folder_name> <backup_file> [true|false]

  • If the last argument is omitted, default is true.
  • It is recommended to pass full backup filename (with prefix and extension).