description	Release-facing overview and installation guide for Google Drive Sync.
status	active
version	0.2.0

Google Drive Sync for Obsidian

Google Drive Sync is a manual, safety-first Obsidian plugin for synchronizing a vault through Google Drive.

It syncs ordinary vault files through a dedicated Google Drive folder and keeps sync metadata in Google Drive appDataFolder. It does not run background sync: every operation is started by the user, destructive local changes require preview approval, and destructive Pull operations create a local rollback snapshot first.

What It Syncs

Included:

• Markdown notes, canvas files, attachments, media files, PDFs, and other ordinary vault files
• hidden files and hidden folders when the Obsidian platform can list and read them
• nested folder structure, recreated from synced file paths

Excluded:

• .obsidian/
• plugin-owned temporary state
• plugin-owned snapshot state
• empty folders

Available Functions

• Connect Google account: authorize Google Drive access for this plugin.
• Create remote vault: create and link a new dedicated Google Drive folder.
• Link existing remote vault: connect this local vault to an existing app-managed Google Drive vault.
• Unlink remote vault: disconnect this device without deleting local files or the Google Drive folder.
• Status: preview local and remote changes without changing local files, Google Drive files, sync metadata, snapshots, settings, or base state.
• Push: upload local vault changes to Google Drive after preview approval.
• Pull: download Google Drive changes into the local vault after preview approval. Pull asks separately before deleting local files.
• Restore last snapshot: restore the most recent local snapshot created before a destructive Pull. Restore is local-only and does not contact Google Drive.
• Adopt Google Drive files: on desktop, open Google's onepick Picker flow in the browser so this app can access ordinary files manually added to the linked Drive folder. Adoption only verifies visibility; Pull still downloads files after preview approval.

All functions are available from Obsidian commands and from the plugin settings tab when their prerequisites are met.

Safety Model

• Sync is manual only. The plugin does not watch files or run background sync.
• Push and Pull show previews before mutation.
• Pull creates a local rotating snapshot before destructive local changes.
• Pull uses system trash first for local deletions; if trash is unavailable, it asks before permanent deletion.
• Conflicts are resolved per file with Local or Google Drive.
• Delete-vs-edit cases are conflicts and are never chosen automatically.
• Status and Adopt Google Drive files are non-mutating.
• Google Drive files remain readable in the linked Drive folder. This plugin is not end-to-end encrypted.
• OAuth tokens are stored through Obsidian secret storage, not in plugin data or sync metadata.

The main Google account connection uses drive.file for visible vault content and drive.appdata for hidden sync metadata. Desktop adoption uses a separate onepick authorization request scoped to drive.file only.

Android is in scope and manifest.json keeps isDesktopOnly: false. The current adoption flow is desktop-only, but core sync commands remain Android-capable.

For more detail, read Safety Model And Known Limitations.

Basic Use

1. Install and enable the plugin.
2. Run Connect Google account.
3. Run Create remote vault for a new sync target, or Link existing remote vault for a previously created app-managed remote vault.
4. Run Status to preview differences.
5. Run Push to send local changes to Google Drive.
6. Run Pull to bring Google Drive changes into the local vault.

When ordinary files are manually uploaded into the linked Drive folder outside this plugin, run Adopt Google Drive files on desktop, then run Status and Pull.

Conflict Behavior

The plugin compares the last synchronized base state, the current local vault, and the current Google Drive folder.

Conflicts happen when both sides changed the same path in incompatible ways, or when one side deleted a path while the other side edited it. The plugin asks you to choose the winning side for each conflicted file.

Path collisions, unsupported Google Drive item types, inaccessible local files, missing metadata, and lock contention block sync until resolved.

Installation

This repository builds a local Obsidian plugin bundle into dist/. It is not a published Community Plugins install yet.

1. Install dependencies:

   pnpm install

2. Provide Google API build configuration in .env:

   cp .env.example .env

   Then edit .env with your Google OAuth and Picker values:

   GOOGLE_OAUTH_CLIENT_ID=...
   GOOGLE_OAUTH_CLIENT_SECRET=...
   GOOGLE_OAUTH_REDIRECT_URI=http://127.0.0.1:42813/oauth2callback
   GOOGLE_PICKER_DEVELOPER_KEY=...
   GOOGLE_PICKER_APP_ID=...
   

   .env is ignored by Git and must not be committed.

3. Build the plugin:

   pnpm build

4. Copy the generated files into your vault plugin folder:

   mkdir -p "/path/to/vault/.obsidian/plugins/gdrive-sync"
   cp dist/main.js dist/manifest.json dist/versions.json \
     "/path/to/vault/.obsidian/plugins/gdrive-sync/"

5. Restart Obsidian, enable community plugins, then enable Google Drive Sync.

Development

Developer documentation starts at docs/index.md.

Useful commands:

pnpm check
pnpm test
pnpm build
pnpm release:check

Run pnpm release:check before preparing a release build.