# Obsidian Vault Backup

A local backup plugin for Obsidian that creates ZIP archives of your entire vault with automatic retention management.

## Features

- **Manual & Automatic Backups**: Create backups on-demand, on startup, or on shutdown
- **Backup Profiles**: Save multiple backup configurations and choose a profile per device
- **Atomic ZIP Creation**: Uses temporary files with atomic rename to ensure backup integrity
- **Flexible File Naming**: Template-based filename generation with date/time variables
- **Configurable Exclusions**: Skip selected vault-relative files and folders
- **Retention Management**: Automatically manage old backups with configurable policies
- **Hidden Files Support**: Includes all files in your vault, including dotfiles
- **Desktop Only**: Optimized for desktop environments (macOS, Windows, Linux)

### Commands

- **Create backup now**: Manually trigger a backup (also available via ribbon icon)
- **Show backup list**: View all existing backups matching your filename template

### Filename Template Variables

Use the following variables in your filename template:

- `{{vault}}`: Vault name (sanitized for filesystem)
- `{{date}}`: Current date (default: YYYY-MM-DD)
- `{{date:FORMAT}}`: Custom date format
- `{{time}}`: Current time (default: HHmmss)
- `{{time:FORMAT}}`: Custom time format
- `{{datetime}}`: Date and time (default: YYYY-MM-DD_HHmmss)
- `{{datetime:FORMAT}}`: Custom datetime format

Example: `{{vault}}_{{datetime:YYYY-MM-DD_HHmmss}}` → `MyVault_2026-01-01_203015.zip`

### Retention Policy Modes

Configure how old backups are managed:

- **Keep last N backups only**: Retain only the most recent N backups
- **Keep backups within days only**: Keep backups created within the specified number of days
- **Keep if both conditions met (AND)**: Backup must satisfy both conditions
- **Keep if either condition met (OR)**: Backup satisfies at least one condition

Set either value to 0 for unlimited retention in that dimension.

### Backup Profiles

Backup profiles let you save multiple complete backup configurations. Each profile includes the backup folder paths, filename template, compression level, excluded paths, automatic backup settings, and retention policy.

The selected profile is saved per device using the device name, so a synced vault can use different backup settings on each desktop.

## Configuration

Access settings via **Settings → Plugin Options → Vault Backup**:

- **Backup profiles**: Create, duplicate, rename, delete, and select the backup profile used on the current device
- **Backup folder path**: Local directory where ZIP files will be saved
- **Filename template**: Pattern for backup filenames (see variables above)
- **Compression level**: ZIP compression (0 = none, 9 = maximum)
- **Excluded paths**: Vault-relative files or folders to skip, one path per line
- **Run on startup**: Automatically backup when Obsidian starts
- **Startup delay**: Milliseconds to wait before startup backup
- **Run on shutdown**: Best-effort backup when Obsidian closes
- **Retention mode**: How to apply retention rules
- **Keep last N backups**: Number of recent backups to preserve
- **Keep backups within days**: Age threshold for backups

## Installation

### Manual Installation

1. Download the latest release files (`main.js`, `manifest.json`, `styles.css`)
2. Create a folder: `<vault>/.obsidian/plugins/vault-backup/`
3. Copy the downloaded files into this folder
4. Reload Obsidian
5. Enable "Vault Backup" in Settings → Community plugins

### From Source

1. Clone this repository
2. Run `npm install` to install dependencies
3. Run `npm run build` to compile
4. Copy `main.js`, `manifest.json`, and `styles.css` to your vault's plugin folder
5. Reload Obsidian and enable the plugin

## Development

### Prerequisites

- Node.js v16 or higher
- npm or yarn

### Setup

```bash
# Install dependencies
npm install

# Development mode (watch for changes)
npm run dev

# Production build
npm run build

# Lint code
npm run lint

# Bump version and release it to github
make release VERSION=0.1.0
```

### Project Structure

```
src/
  main.ts              # Plugin entry point and lifecycle
  settings.ts          # Settings interface and UI
  types.ts             # TypeScript type definitions
  backup.ts            # Backup execution and concurrency control
  zip.ts               # ZIP file creation with atomic operations
  template.ts          # Filename template parsing
  retention.ts         # Backup retention management
  ui/
    backup-list-modal.ts  # Backup list UI
```

## How It Works

### Atomic Backup Process

1. **Temporary file creation**: Creates `<filename>.tmp.<random>` in the backup folder
2. **ZIP generation**: Streams vault files into the temporary archive, skipping excluded paths
3. **Atomic rename**: Renames temp file to final `.zip` filename
4. **Retention cleanup**: Removes old backups according to retention policy

This approach ensures backups are never corrupted, even if the process is interrupted.

### Excluded Paths

Excluded paths are matched relative to the vault root. Enter one file or folder per line in settings. For example, `private.md` excludes only that file, while `attachments` excludes the folder and everything inside it. Leading slashes, trailing slashes, and Windows backslashes are normalized automatically. Glob patterns and regular expressions are not supported.

### Concurrency Control

Only one backup can run at a time. If a backup is already in progress, additional requests are rejected with a notice.

### Startup/Shutdown Behavior

- **Startup backup**: Runs after a configurable delay to avoid interfering with vault loading
- **Shutdown backup**: Best-effort only; may not complete if Obsidian is force-quit or crashes

## Privacy & Security

- **100% Local**: All backups are stored locally; no data is sent to external services
- **No Telemetry**: No analytics or tracking
- **Desktop Only**: Requires filesystem access (not compatible with mobile)

## Troubleshooting

### Backup fails with "input source must be valid"

Ensure the vault path exists and is accessible. Check the developer console (Cmd+Opt+I / Ctrl+Shift+I) for detailed error messages.

### Temp files left in backup folder

If temp files (`.tmp.*`) remain after a failed backup, they can be safely deleted manually.

### Old backups not being deleted

Verify your retention settings and ensure the filename template matches existing backup files.

## License

This plugin is licensed under the 0-BSD License.

## Support

If you find this plugin useful, consider supporting its development.