Full Vault Mirror Sync

Full Vault Mirror Sync is a Windows-only Obsidian Community Plugin that performs one-way mirror sync from a source folder to a target folder by using Windows robocopy.

Traditional Chinese documentation: README.zh-TW.md

Important Warning

This plugin performs mirror sync with robocopy /MIR. The target folder is forced to match the source folder. Extra files in the target folder can be deleted. If a file is deleted from the source, it can also be deleted from the target on the next sync. This plugin is not a backup tool and is not a versioned backup system.

Use Case

Use this plugin when you want one folder to stay aligned with another folder on the same Windows machine, such as:

• mirroring your current Obsidian vault to a local mirror folder
• keeping a working folder synchronized to another Windows path
• maintaining a second copy that should match the source layout and file metadata

Features

• Windows-only desktop plugin for Obsidian
• Source path defaults to the current vault root
• Source path can be edited manually
• User-defined destination folder
• Manual sync button
• Optional timer-based automatic sync
• Optional startup sync shortly after Obsidian loads when automatic sync is enabled
• robocopy mirror sync with /MIR /COPY:DAT /DCOPY:DAT /R:3 /W:1 /FFT /XJ
• Pre-sync safety validation for blank paths, same paths, and drive-root paths
• Clear destination-path availability error handling
• Confirmation prompt before the first sync into a non-empty target folder
• Post-sync metadata verification for file presence, file size, modified time tolerance, and unexpected extra files
• Automatic retry after validation failure, up to 3 additional attempts when enabled
• Bilingual warnings and documentation in English and Traditional Chinese

What This Plugin Does Not Do

• no bidirectional sync
• no cloud sync
• no telemetry
• no pCloud API integration
• no Git integration
• no ZIP backup
• no versioned backup
• no checksum-based verification in the current release
• no API key requirement

Requirements

• Windows desktop version of Obsidian
• Obsidian 1.5.0 or later
• Windows robocopy
• Node.js 18 or later for local development
• npm for local development

Installation

Community Plugin submission support is prepared in this repository, but availability inside the public Obsidian Community Plugins catalog depends on the official review and merge process.

If you are installing from a GitHub release, download these assets from the matching release tag:

• main.js
• manifest.json
• styles.css

Manual Installation

1. Create this folder inside your vault:

<YourVault>\.obsidian\plugins\full-vault-mirror-sync\

2. Copy these files into that folder:

• main.js
• manifest.json
• styles.css

3. Open Obsidian.
4. Go to Settings -> Community plugins.
5. Enable community plugins if needed.
6. Enable Full Vault Mirror Sync.

Settings

• Source folder path: full Windows path for the source folder. Defaults to the current vault root.
• Target folder path: full Windows path for the mirror target.
• Sync interval: timer interval in minutes for automatic sync.
• Enable automatic sync: starts timer-based sync only after you enable it.
• Sync once on Obsidian startup: runs one sync shortly after Obsidian starts. This only works when automatic sync is enabled.
• Manual sync: runs the real robocopy mirror flow.
• Verify after sync: runs metadata-based post-sync validation.
• Retry automatically on verification failure: retries sync up to 3 more times when validation fails.

Safety Notes

• This plugin is a mirror sync tool, not a backup tool.
• The target folder is expected to become identical to the source folder.
• Deleting a file from the source can lead to deletion in the target on the next mirror sync.
• Do not use a drive root such as C:\ or D:\ as either source or target.
• Do not point the target to a folder that contains unrelated important files.
• The plugin warns before the first sync into a non-empty target folder.

More details: docs/SAFETY.md

Privacy

This plugin does not upload your data, does not call cloud APIs, and does not collect telemetry. Sync and validation run locally on your Windows machine.

No API key is required.

Verification

When Verify after sync is enabled, the plugin checks:

• every source file exists in the target
• source and target file sizes match
• source and target modified times are within 3 seconds
• the target does not contain extra files or directories that no longer exist in the source

The current release does not perform checksum validation.

The plugin excludes its own runtime state file from post-sync validation to avoid false failures caused by status updates after sync.

If sync cannot start or cannot finish before validation, post-sync validation is marked as skipped.

Troubleshooting

When the target drive or destination folder is unavailable, the sync status becomes Failed.

The plugin shows a clear destination-path error such as:

Destination path is not available: P:\ObsidianMirror

Robocopy exit codes are not traditional success/failure codes.

• Exit codes 0 through 7 are treated as successful or acceptable.
• Exit code 0 usually means no files needed to be copied.
• Exit code 1 means files were copied successfully.
• Exit code 3 can mean files were copied and additional differences were handled.
• Exit code 8 or higher means failure.

Known Limitations

• Windows desktop only
• relies on robocopy
• verification does not use checksums
• verification compares metadata and relative paths only
• the plugin is designed for one-way mirror sync, not collaborative or two-way workflows

Development

Install dependencies:

npm install

Build once:

npm run build

Watch mode:

npm run dev

Main source files:

• src/main.ts
• manifest.json
• styles.css

Supporting docs:

• docs/TESTING.md
• docs/SAFETY.md
• docs/RELEASE.md

Release

• Keep the release tag exactly equal to manifest.json version, for example 0.1.0
• Do not prefix the tag with v
• Attach main.js, manifest.json, and styles.css to the GitHub release
• Do not upload only source.zip or source.tar.gz

Detailed release notes: docs/RELEASE.md

License

MIT. See LICENSE.