AFTRIMGE

Documentation

Recovery and restore

Restoring a past version of a file

  1. Select the file and the version you want.
  2. AFTRIMGE shows a plan: where it will write, and whether the file on disk has changed since it was last recorded.
  3. Choose how:
  4. Copy writes the version beside the original under a new name. It never overwrites anything.
  5. In place replaces the file. It is refused if the plan found a conflict.
  6. Force replaces the file even though a conflict was shown. It is the only way a restore overwrites work AFTRIMGE did not record.
  7. AFTRIMGE checks the stored bytes against their identity, writes them to a temporary file beside the target, checks that file, replaces the target, and checks the result.

A restore adds to history. It never removes later versions. A restore can only write inside the project it belongs to.

If a restore fails, for example because the disk is full, it removes its own temporary file and leaves the existing file as it was.

A restore refuses a destination that:

  • passes through a junction or symbolic link, which could lead outside the watched folder (recording does not follow junctions or symbolic links out of a watched folder either);
  • has a name Windows treats as a device: CON, PRN, AUX, NUL, COM1 to COM9 or LPT1 to LPT9, with or without an extension;
  • has a name ending in a dot or a space;
  • names an alternate data stream (contains a colon);
  • contains characters Windows does not allow in file names.

On Windows, two recorded files whose names differ only in letter case (possible when the history came from a case-sensitive system) cannot overwrite each other on restore: the second is reported as a conflict.

Bringing back a deleted file

Deleted files keep their history. Restoring one of their versions recreates the file without merging it into another file that has since taken its path.

Restoring a whole moment

The engine can restore a whole project to how it stood at a recorded instant: it restores and recreates files, skips anything in conflict, and never proposes deleting a file. The interface does not currently offer this. Restore files one at a time.

If AFTRIMGE closes during an operation

AFTRIMGE was tested by terminating its process repeatedly during capture, during retention and collection, and during restore:

  • the database was never corrupted;
  • no version that was meant to be kept lost its bytes;
  • a restored file was always one complete version, never a mixture.

What can be left behind:

  • partly written bytes in the archive's staging area, removed at next start;
  • bytes with no record, reported as UNTRACKED and removed by a later sweep;
  • a hidden temporary file named .name.number.aftrimge.tmp beside a file that was being restored, where the number is the process id of the AFTRIMGE that wrote it. It can be deleted. AFTRIMGE removes such a file itself during the first scan of the watched folder when watching starts, but only if it is a regular file, its name matches that pattern exactly, the number is not the running AFTRIMGE's process id, and it is older than 15 minutes. Nothing else is removed.

If AFTRIMGE fails internally, it writes a short record to logs/panic.log in the archive folder before it stops: the time, the version, the thread, the source location and the failure message. When that file passes 256 KB it is started afresh and the previous one is kept as panic.log.1. The record stays on your computer; it is not crash reporting and nothing is sent.

This covers a process that stops. A power cut is a different failure. AFTRIMGE flushes each file to disk before making it visible, but power loss has not been tested.

Checking the archive

  • The storage ledger lists content whose bytes are missing and bytes with no record.
  • Each object can be verified: its bytes are read in full and hashed, and the result is one of VERIFIED, CORRUPT, MISSING, UNREADABLE or UNVERIFIED. A wrong size recorded in the database is reported separately and is never called corruption.
  • Verify whole archive, in the storage ledger view, reads every stored object AFTRIMGE has a record of in full and checks its SHA-256. It shows progress and can be stopped. It changes nothing. The result is one of:
  • VERIFIED: every object was read and matched;
  • DAMAGE FOUND: corrupt or missing objects, listed, each with Open in ledger, where repair is offered;
  • NOT VERIFIED: some objects could not be read;
  • CANCELLED: stopped before the end; it says nothing about objects it did not reach;
  • nothing stored yet, or that the check could not run.

Diagnostic report

The Diagnostics button at the right of the status bar saves a JSON report to a place you choose. It contains:

  • the AFTRIMGE version, the database format, the operating system and architecture, and whether the copy is portable;
  • counts: projects, files, versions, events, objects recorded and objects on disk, stored bytes, database size, preservations, archived images and database backups made before format upgrades;
  • the result of SQLite's quick_check;
  • the names and sizes of the daily log files, and how many crash records exist;
  • up to the last 400 log lines, reduced so that every field value except a plain number reads <redacted>, and any message that looks like it carries a path is redacted whole.

It contains no file contents, no file names or paths, no project names or folder locations, no archive location, and no account or computer names. AFTRIMGE does not send it anywhere.

Repairing a damaged object

If an object is corrupt or missing, AFTRIMGE looks for a source that still has exactly that content, such as the watched file itself, and verifies it before using it. If no verified source exists, it says so and changes nothing.

Backing up the archive

There is no export command. The archive folder is the backup.

  1. Close AFTRIMGE.
  2. Copy the whole archive folder (see Data and storage). Copy aftrimge.db together with aftrimge.db-wal: during testing, a copy of aftrimge.db alone contained no tables.
  3. To restore, close AFTRIMGE and put the folder back in the same place.
  4. Open the storage ledger, check for MISSING or UNTRACKED entries, and run Verify whole archive.

Copying a closed archive and reopening it has been tested. Restoring onto a different computer, or into a different version of AFTRIMGE, has not.

If AFTRIMGE does not start

It shows a dialog naming the cause and where the archive is, writes the cause to the log, and exits. Copy the whole archive folder somewhere safe before trying anything else.

Common causes:

  • The archive was written by a newer version. Install that version again.
  • The database is damaged. AFTRIMGE will not recreate it over the top of your data. Keep the copy you made.
  • The backup before a database format upgrade could not be made, for example because the disk is full. The database was not upgraded and nothing was changed. Free space and start AFTRIMGE again.

If you launch AFTRIMGE twice

Only one copy of AFTRIMGE can have an archive open. Starting AFTRIMGE while it is already open with the same archive shows AFTRIMGE is already open with this archive and exits without opening anything. It does not bring the open window forward; switch to that window yourself.

An installed copy and a portable copy use different archives, so they can run at the same time.

The check is an operating-system lock on aftrimge.lock in the archive folder. The operating system releases it when AFTRIMGE ends in any way, including a crash, so there is never a stale lock to remove. Do not delete that file.

Source: docs/RECOVERY.md