Ztsd Vault Backup

A cross-platform, zero-dependency backup plugin for Obsidian that creates compressed, cryptographically verified backups of your vault using tar archiving and Zstandard (ZSTD) compression.

Built entirely in pure TypeScript/JavaScript, this plugin runs inside Obsidian's desktop environment without requiring any external command-line binaries (like tar or zstd) installed on your computer.

🚀 Key Features

• Pure JS/TS Compression Stack: Uses optimized, in-process JavaScript libraries (tar and zstdify) to compress your vault, ensuring 100% portability across Windows, macOS, and Linux.

• SHA-256 Integrity Verification: Generates a sidecar .sha256 checksum file for every backup. Before restoring, the plugin automatically validates the archive integrity to protect against silent data corruption.

• Non-Destructive Restoration: Restoration never overwrites your live vault directly. Instead, it extracts the selected backup snapshot into a dedicated, timestamped folder inside your configured recovery directory, allowing you to review files before merging them.

• Configurable Pruning: Limit the number of backups stored locally to save disk space. Easily set your preferred limit (e.g., keep last 10 backups) using a simple number box in the settings.

• Simple GUI Controls:

  • Left-ribbon icon (left arrow) to open the restoration snapshot list view.
  • Settings panel with configuration fields and manual Backup and Restore buttons.

🔒 Why This Plugin is Safe to Use

1. No Destructive Overwrites: Restoring a backup does not touch your active vault files. It extracts the files to a separate subdirectory, letting you inspect or retrieve specific files side-by-side without risking your current day's work.
2. In-Process execution (No Shell Spawning): Unlike plugins that execute terminal shell commands (which can introduce OS command injection vulnerabilities or fail on pathnames containing spaces), all tar and compression logic runs inside Node.js's safe API layer.
3. Checksum Verification: Every backup creates a .sha256 validation file. The restore process reads the checksum and validates the archive content before attempting any decompression, ensuring you never restore corrupted archives.
4. Excluded Cache/Metadata folders: To keep backups small and clean, system metadata folders like .obsidian (plugin cache/configs) and .trash are automatically excluded from the archives.

💡 Usecases

• Pre-Refactoring Checkpoint: Creating a quick backup before performing bulk operations like bulk search-and-replace, folder restructurings, or heavy plugin updates.
• Accidental File Recovery: Easily roll back to a prior state of your note or retrieve deleted attachment assets without searching through cloud syncing histories.
• Storage-Efficient Archiving: Zstandard provides significantly better compression ratios and speeds than standard GZIP or ZIP, saving local hard drive space.

⚙️ Configuration

Open Obsidian Settings > Zstd Backup:

1. Vault Directory: The absolute path to your active Obsidian vault.
2. Backup Directory: The directory where your .tar.zst and .sha256 files will be saved.
3. Enable Pruning: Toggle on/off the automatic cleanup of older backups.
4. Max Backups: A text field to enter the maximum number of archives to retain.
5. Manual actions: Click Backup to run an immediate backup, or Restore to view the snapshot recovery panel.

🛠️ Development

If you want to compile and build the plugin locally:

1. Clone this repository.
2. Run npm install to install dependencies.
3. Create a local.config.json file in the root directory to map your test vault path:

   {
     "targetDir": "/path/to/your/test/vault/.obsidian/plugins/zstd-backup/"
   }
   

4. Run npm run dev to start the watch compiler.
5. Run npm run build to build a production release.

📄 License

This project is licensed under the MIT License.