# Backups and recovery

> Every change HTML Clay or another program makes to a file is kept as a complete, uncompressed HTML version you can open, read, and restore.

Source: https://htmlclay.com/docs/guide/backups/

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.