How It Works

What actually happens when you back up

The Folder Structure

When you run borg-anchor init ~/backups/, it creates:

~/backups/
├── .borg-anchor.json   ← config for borg-anchor
├── .git/               ← stores your Bitcoin key
└── storage/            ← where Borg keeps everything
    ├── data/           ← your files (chunked, compressed)
    ├── index.1         ← lookup table to find chunks
    └── config          ← Borg settings

Where are my files?

Not stored as regular files. Borg splits them into chunks, compresses them, and stores them in data/. That's why you need borg-anchor restore to get them back.

What's a chunk?

Borg splits files into pieces (chunks). If the same chunk appears in multiple files or backups, it's only stored once. That's deduplication.

Backups and Archives

Each time you run borg-anchor backup, it creates an archive - a snapshot of your folder at that moment.

~/backups/storage/
└── contains:
    ├── archive: "my-backup"        (Jan 4, 10:00)
    ├── archive: "my-backup-2"      (Jan 5, 10:00)
    └── archive: "weekly"           (Jan 7, 10:00)

All archives share the same chunks. If a file didn't change between backups, it's not stored again.

How does it know where files came from?

Each archive stores metadata: the original path, permissions, and which chunks make up each file.

Archive "my-backup":
├── /home/you/Documents/notes.txt → chunks [A, B]
├── /home/you/Documents/photo.jpg → chunks [C, D, E]
└── /home/you/Documents/report.pdf → chunks [F, G]

When you restore, Borg recreates the original folder structure.

Can I back up multiple folders?

Yes. Each backup creates a separate archive:

borg-anchor backup ~/Documents/ --name docs
borg-anchor backup ~/Photos/ --name photos

Both are stored in the same place, deduplicated together.

The Index and Config

What's index.1?

A lookup table so Borg can find chunks quickly:

chunk ID → location in data/

Without it, Borg would have to scan everything to find a file.

What's config?

Repository settings: encryption mode, version, unique ID. Just bookkeeping.

The .git Folder

This is not from Borg. borg-anchor creates it to store your Bitcoin private key:

git config nostr.privkey YOUR_KEY

Git config is just a convenient place to store it locally per-backup-folder.

Bitcoin Anchoring

After each backup, Borg generates a fingerprint - a SHA-256 hash of the archive. If even one byte changes, the fingerprint is completely different.

borg-anchor takes that fingerprint and records it in a Bitcoin transaction. This creates proof that your backup existed at a specific point in time.

Your files → Borg archive → Fingerprint → Bitcoin transaction

Anyone can verify: look up the transaction, check the fingerprint matches your backup.