dwmc-backup

Warning: This project is a prototype and is not ready for production use. Test your backups and restores before relying on it for important data.

dwmc-backup is a small Deno command-line tool for creating compressed incremental filesystem backups and restoring a selected backup point. It uses GNU tar snapshot metadata to store only changes after the first backup.

Features

• Incremental backups with GNU tar's --listed-incremental format
• Parallel gzip compression with pigz
• Timestamped backup archives
• Interactive restore-point selection with fzf
• Restore into a separate directory without overwriting the source
• TOML configuration in the user's home directory
• Activity and error logs
• Standalone binary and Docker-based build options

Requirements

• A Unix-like operating system
• Deno to run from source or compile the binary
• GNU tar
• pigz
• fzf
• Docker, only if using the Docker helper

All three runtime tools must be available on PATH, including fzf when creating backups.

For Debian or Ubuntu:

sudo apt install tar pigz fzf

Configuration

Create ~/.dwmc-backup.conf with absolute paths:

SOURCE_DIR = '/home/user/documents'
BACKUP_DIR = '/mnt/backups/documents'

• SOURCE_DIR is the directory to back up and must already exist.
• BACKUP_DIR stores archives, metadata, logs, and restored files. It is created automatically when missing.
• Keep BACKUP_DIR outside SOURCE_DIR to prevent backups from including themselves.

If the configuration file is missing, the program offers to create a template and then exits so that you can edit it.

Usage

Run from source

Create a backup:

deno task run backup

Restore a backup point:

deno task run restore

Build a standalone binary

deno task compile

The command creates dwmc-backup.bin. Deno is not required to run the compiled binary, but GNU tar, pigz, and fzf are still required.

./dwmc-backup.bin backup
./dwmc-backup.bin restore

Build or run with Docker

The helper script must currently be run from the scripts directory:

cd scripts
./docker-deno.sh compile
./docker-deno.sh run backup

The container only mounts the project directory. A host SOURCE_DIR or BACKUP_DIR is unavailable inside the container unless the script is extended with the required volume mounts. The compiled binary is therefore the most practical Docker-generated artifact for normal host use.

How Backups Work

The first backup command creates a full archive and backup.snar, the GNU tar snapshot metadata file. Each later command uses that metadata to create an incremental archive containing changes since the previous backup.

Archives are written as:

BACKUP_DIR/snapshots/backup_<unix-timestamp>.tar.gz

Treat backup.snar and every archive in snapshots/ as one backup set. Do not delete an intermediate archive: later restore points depend on the complete chain.

How Restore Works

Run the restore command and select an archive in fzf:

deno task run restore

The program then:

1. Deletes any existing BACKUP_DIR/restore directory.
2. Recreates the restore directory.
3. Extracts archives in order, from the first backup through the selected backup.
4. Leaves the recovered tree under BACKUP_DIR/restore for inspection or manual copying.

The source directory is not modified. Always inspect the restored data before replacing live files.

Backup Directory Layout

BACKUP_DIR/
|-- backup.snar
|-- snapshots/
|   `-- backup_<unix-timestamp>.tar.gz
|-- restore/
|-- _backup.log
`-- _error.log

• backup.snar: state used to create the incremental chain
• snapshots/: compressed backup archives
• restore/: reconstructed files from the latest restore operation
• _backup.log: backup and restore activity
• _error.log: runtime errors and stack traces

Operating Notes

• Run only one backup at a time. Concurrent runs can corrupt snapshot state or overwrite archives created in the same second.
• Back up the entire BACKUP_DIR, including backup.snar, when copying a backup set elsewhere.
• The project does not provide scheduling, retention, pruning, encryption, remote storage, archive verification, or locking.
• Regularly perform test restores and verify the recovered files.
• Review _error.log after a failed operation.

Development

The implementation is contained in main.ts. Deno tasks are defined in deno.json, and dependency versions are recorded in deno.lock.

deno task run backup
deno task compile

There is currently no automated test suite or release workflow.

License

Licensed under the MIT License.