Backups and recovery

HTML Clay keeps the file you opened, every file you save, and every change another program makes. Each one is a complete version, so a bad edit is never the end of a document.

What gets a version#

A version is captured at five moments:

• Opened. The starting point, when an explicitly opened file is first served.
• Before the first save. The original content.
• Saved. Every incoming save.
• Before an old version is restored. The current file is copied first.
• Changed on disk. Another program’s outside edit to the file.

Every write keeps a restorable previous version, including writes made by a program over the wire.

Retention is the union of two rules: the newest 20 versions are always kept, plus every version from the last 60 days.

Plain files you can open without the app#

The history is plain files. Every version is a complete, uncompressed .html file in the Backups folder, under <os-config-dir>/htmlclay/versions.

Choose Backups from the tray menu to open that folder in your file manager. Each document appears there under its path inside Backups, labelled like Backups / notes.htmlclay, and each version is a complete HTML file. Each version has a readable local timestamp in its name (2026-08-27-14-03-52-431-0400.html), so you can open and read any version even if HTML Clay is gone. Each one is a full, uncompressed copy, so saving a 1 MB file 20 times uses about 20 MB of disk space.

Restore only after making a safety copy#

Before an old version replaces the current file, HTML Clay backs up what is there now. If that copy cannot be made, the restore is refused.

History follows the document#

Rename or move a .htmlclay file and its history follows, because the identity is the documentid attribute on <html>. Make a copy and the copy gets a fresh identity, so its edits never mix with the original. Plain .html files are the exception: their history is keyed by location, so moving one leaves that history behind.

Other behavior worth knowing#

• Opening is read-only. A file you open and never save stays byte for byte unchanged.
• Opening leaves no permanent copy. A first-open snapshot under a freshly minted identity that no save ever makes durable is deleted after 7 days.
• Consecutive identical versions collapse. The same content is never stored twice in a row.
• An outside edit is backed up before your save wins. The save succeeds and the previous bytes remain in Backups.
• A save replaces the whole file. HTML Clay writes and flushes a temporary file, then renames it over the target. On macOS and Linux the directory is flushed too; on Windows that final directory flush is skipped.