GitHub Vault Sync

简体中文

v0.2.0 (2026-10-16): adds non-blocking media optimization advice, a fifth settings page, guarded conversion commands with copy-all and synchronized copied states, AVIF Git LFS migration, and a guarded remote delete-and-recreate workflow. Download the single v0.2.0 installation ZIP and read the release notes. Native Windows Obsidian GUI acceptance remains deferred; see the validation scope and known limits.

· Developer history

GitHub Vault Sync is an Obsidian desktop plugin for synchronizing a vault with a separate private GitHub repository. This public repository contains only the plugin's source code and distributable releases. Do not use this public repository for your notes or credentials.

UI motion tour (v0.1.3)

These short illustrative UI-motion demos use the plugin stylesheet and representative settings/preview markup with sample data. They show state changes, preview-first conflict review, and encrypted-settings boundaries; they are not recordings of a live Obsidian session and do not perform a sync. The approved videos are H.264 MP4 files at 1280×720 and 30 fps. On GitHub, use the direct MP4 links; Markdown viewers that allow HTML video may also show the inline player.

Status flow: local changes → remote check → preview → complete

Watch the status-flow MP4 · 4.8s

Preview → choose → confirm

Watch the preview-flow MP4 · 7.2s

Encrypted-settings boundary

Watch the encrypted-boundary MP4 · 4.8s

Install the v0.2.0 release

v0.2.0 retains preview-first synchronization and adds media optimization guidance, five independent settings pages, safer batch-copy interactions, and a guarded remote repository rebuild workflow. See the release notes and standalone install/upgrade guide.

1. Back up your Obsidian vault. Install Git; install Git LFS before syncing images or other attachments matched by the plugin's LFS rules.

2. Open this project's GitHub Releases page and download github-vault-sync-0.2.0.zip. The only manually uploaded release asset is this ZIP; the same file is kept in releases/github-vault-sync-0.2.0.zip. GitHub’s automatic “Source code (zip/tar.gz)” downloads are not installable plugin bundles because the project root omits the compiled main.js.

3. Save your notes and exit Obsidian normally, then extract the ZIP into <Vault>/.obsidian/plugins/. The resulting files must be:

   <Vault>/.obsidian/plugins/github-vault-sync/manifest.json
   <Vault>/.obsidian/plugins/github-vault-sync/main.js
   <Vault>/.obsidian/plugins/github-vault-sync/styles.css
   

   On Windows, a typical destination is C:\Users\<you>\Documents\YourVault\.obsidian\plugins\github-vault-sync\; on macOS, it is <Vault>/.obsidian/plugins/github-vault-sync/. When updating, keep the existing local data.json rather than replacing the entire plugin directory.

   Avoid an extra nested github-vault-sync/github-vault-sync/ directory. The ZIP already contains every plugin file and bilingual setup instructions: no separate Release downloads, Node.js, or pnpm are needed for manual installation. Git and, where applicable, Git LFS remain separate system prerequisites. The ZIP contains no tokens, recovery keys, or personal vault data.

4. Open Obsidian again. In Settings → Community plugins, enable GitHub Vault Sync. Requires Obsidian desktop 1.13.0+ on Windows or macOS (Linux desktop is also supported); mobile Obsidian is not supported. The same ZIP is used for both Windows and macOS.

If you already use a local pre-release labeled 0.4.0, public 0.1.0 was the first public release; 0.2.0 continues that public series and is not a downgrade or upgrade of the internal 0.4.0 build. You need not replace your working installation merely to download the public package. Back up your vault before any manual replacement and leave local data.json in place.

Connect your own private vault repository

1. In plugin settings, connect GitHub using a repository-scoped personal access token (PAT) with read/write permission for your private vault repository. Do not paste the PAT into this public repository or a chat. Browser Device Flow is available if you supply your own GitHub OAuth App Client ID.
2. Create or bind an existing private vault repository in the plugin. Select the intended main branch and review the first-binding preview. This public plugin repository is not the vault repository.
3. Keep a separate local vault backup. Do not run another actively configured vault-sync plugin against the same files at the same time.

Synchronize notes safely

Select Preview and sync in plugin settings or the Sync Center. Before any upload, the plugin compares the local working tree and fetched remote commit, grouping changes in this order: (1) Markdown notes, (2) note-folder attachments, (3) Obsidian plugin/settings and encrypted snapshots, (4) other files. A note changed on both devices can be viewed side by side.

Choose one conflict policy for that run: prefer this device, prefer the repository, or review each note. The priority applies only when the same Markdown path changed on both sides. Independent changes are merged; plugin configurations, encrypted archives, and binary attachments require file-level review. The losing Markdown version is saved locally under .github-vault-sync-conflicts/, which is not uploaded. File times can help review, but clock times do not prove which text is newest. If local content or the remote commit changes after preview, the plugin rejects the stale approval and asks you to preview again. No force push is performed.

Progress shows verified staging file counts and Git/LFS object progress where Git reports it; otherwise the transfer indicator remains indeterminate rather than inventing a percentage. Timely checking notices local changes after a configurable delay (default 90 seconds) and checks GitHub every five minutes. It never uploads without your explicit preview and confirmation.

Media optimization before upload (v0.2.0)

During a full sync preview, v0.2.0 lists included PNG/JPG/JPEG, PDF, MP4, and GIF files larger than the configurable threshold. These suggestions never block synchronization, and the plugin does not execute the conversions. The Media optimization settings page controls the threshold (default 2 MB), media-only glob exclusions, the image PSNR floor (default 35 dB), and whether estimated savings are shown.

Each finding has a Copy conversion command action, and Copy all conversion commands copies every finding, including entries on later pages. A successful batch copy immediately updates the visible buttons and entries loaded afterward; scrolling to the end loads 30 more findings and updates the displayed count. Run the copied commands from the vault root in a terminal; on Windows use Git Bash. Images require Pillow and pillow-avif-plugin, PDFs require Ghostscript, MP4 commands require FFmpeg with libsvtav1, and GIF commands require FFmpeg with libwebp. PNG starts at AVIF q70 and JPG at q60; the command then tries higher quality steps through q100 until the configured PSNR floor is met. If the floor still cannot be met, it leaves no converted file. Existing destinations are not overwritten, and colliding output names receive a short hash.

PDF commands use Ghostscript /ebook, MP4 commands use AV1, and GIF commands produce animated WebP. Estimated savings are projections from the measured vault samples, not guarantees for a particular file. Lossy replacement is irreversible: keep a cold backup, inspect the generated files, update note links yourself, and open a fresh sync preview afterward. AVIF is included in the default Git LFS rules and is added once when migrating pre-0.2.0 settings.

Advanced settings also include a Remote rebuild checklist. It only displays the current private repository and the required backup, history-optimization, and second-device pause checks; it never deletes or recreates a repository.

The Account & repository page also includes Remote delete-and-recreate. It first reads the remote state and creates and verifies a Git bundle outside the vault. The dangerous action stays disabled until the user confirms the cold backup and desired history, the second-device pause, permanent Git/LFS history loss, and the exact owner/repo. Only then does it delete the repository, verify the 404, recreate it privately with the original issues/wiki settings, force-push the current local history, and verify the resulting remote SHA. A failure after deletion never automatically retries deletion; inspect the reported stage and recover from the bundle or the current repository instead. On the other device, back up the old clone, clone the rebuilt repository again and run git lfs pull; verify the plugin binding and recovery key before resuming two-device sync.

Encrypted plugin settings and recovery key

Plugin data.json, credential dotfiles, and explicitly excluded exceptional plugin directories are never committed as plaintext. If enabled, client-side AES-256-GCM encryption stores their backed-up contents in .github-vault-sync-encrypted/vault.gvs. The encryption key is local only. Open View and copy recovery key to reveal it in a modal and copy it; closing the modal hides the displayed value. Keep an independent, secure copy outside your vault and outside GitHub. Anyone with both the encrypted repository and the key can decrypt its plugin credentials; losing the key makes the encrypted copy unrecoverable.

On another desktop device, install this plugin, bind the same private repository, import the recovery key locally, pull the encrypted bundle, then choose Restore encrypted settings. New recovery keys and restore backups default to the current user’s Library/Application Support/github-vault-sync-backups/ on macOS, %APPDATA%\github-vault-sync-backups\ on Windows, and the XDG user data directory on Linux. Keep the Vault and its local data.json protected by your OS account permissions; Windows ACLs are not equivalent to Unix chmod. Restoration first backs up files that would be overwritten and preserves the current device's GitHub login by default. Restart Obsidian afterward. Incoming encrypted or executable plugin changes pause automatic processing until reviewed.

Cross-platform verification

The macOS/Windows CI runs TypeScript checks, temporary local Git/Git LFS integration tests, and a production build. Release-tag CI also checks that the ZIP matches the built files; main/PR development builds do not require an unreleased ZIP. This is not a Windows Obsidian GUI session or a guarantee for every third-party theme or Git installation. Separate macOS Obsidian 1.14.4 checks covered the running v0.2.0 version, five settings pages, media preview/copy interactions, safe settings migration, and read-only remote-rebuild confirmation gating. Native Windows Obsidian GUI acceptance remains deferred. See the validation scope; report host-specific issues with the Obsidian version, OS, and non-secret diagnostic details. No real vault or GitHub token is used in CI.

Build from source

pnpm install --frozen-lockfile
pnpm typecheck
pnpm test
pnpm build

The build creates main.js in the project root; release maintainers can run python scripts/release_archive.py build to create and verify the allowlisted ZIP. The ZIP uses the independent bilingual guides under docs/install/, not these repository READMEs; its online video/documentation links point to the release tag. Only manifest.json, main.js, and styles.css belong in an installed plugin folder. For the ready-to-install package use the single release ZIP instead. See the developer handoff for architecture, design decisions, tests, and the public-safe development conversation timeline.

Security note

A private repository is not an encryption key or an offline backup. Review changes before upload, respect Git LFS limits, and keep your recovery key outside both repositories. The current source scan is heuristic, not a formal guarantee that arbitrary notes or third-party plugin code cannot contain secrets. This project does not transmit your vault to the public plugin repository.