Google Drive Sync for Obsidian

The plugin allows you to manage multiple independent vaults within a single Google account using a tagging system.

Vault Identification

• When a vault is first set up, a folder is created in Google Drive named after your vault. This folder is tagged with the vault name and stores the name internally.
• Each file in the vault is also tagged with the vault name in its Google Drive properties.
• You can safely rename or change the color of the folder in Google Drive; syncing will not break.

Managing Multiple Vaults

• To sync multiple devices to the same vault: Ensure the local vault names are identical on all devices.
• To create a new, separate vault: Create a local vault with a unique name. Do not simply rename an existing synced vault locally, as this will break the connection to its specific Google Drive folder. Instead, create a new vault, enable the plugin, and move files into it via the Obsidian app.

To prevent data loss or sync errors, adhere to these rules:

• Backup your vault: Always create a backup before using the plugin.
• No manual uploads: Do NOT manually upload files into the generated Google Drive folder using other sync tools. The plugin cannot see these files and it may cause data loss.
• No external file edits: Do NOT modify files outside of the Obsidian app. The plugin tracks changes via the Obsidian API; external changes will not be detected.
• Avoid path conflicts: If you delete/rename a file with no extension and then immediately create a folder with the exact same path, run a Sync between those two actions to prevent errors.
• Internet stability: Ensure a stable connection during sync. Closing the app or losing connection mid-sync can lead to data corruption.
• Conflict resolution: The plugin uses local file prioritization to resolve conflicts automatically. There is no manual conflict resolution interface.

The plugin supports both pulling from and pushing to Google Drive:

Pulling (Google Drive $\rightarrow$ Obsidian)

• The plugin automatically pulls changes from Google Drive once when Obsidian finishes opening the vault.
• This process pulls cloud files to your local device.
• To trigger this manually, run the Pull from Google Drive command.
• Note: Pulling new plugins or configurations may require an Obsidian restart.

Pushing (Obsidian $\rightarrow$ Google Drive)

• To sync local changes to the cloud, click the sync button on the ribbon or run the Push to Google Drive command from the command palette.
• Pushing automatically performs a pull before pushing changes to ensure synchronization.
• Recommendation: Sync before closing Obsidian to ensure the cloud state is up to date.

Automatic Syncing

• You can enable Automatically push changes in the plugin settings. When enabled, the plugin will push changes to Google Drive one minute after the most recent local file change. This is disabled by default.

The ObsidianGoogleDrive class manages the synchronization state. Developers interacting with the plugin instance can use the following methods to control the sync process:

• startSync(): Initiates a sync session. Checks for internet connectivity first. Throws an error if no connection is found. Sets syncing to true and updates the ribbon icon.
• endSync(syncNotice?: Notice, retainConfigChanges?: boolean): Finalizes a sync session. Updates lastSyncedAt and changesToken. If retainConfigChanges is true, it ensures configuration files are synced. Returns true on success.
• abortSync(syncNotice?: Notice): Stops the current sync attempt, clears the spinning ribbon icon, and resets the syncing state.
• saveSettings(): Persists the current PluginSettings to disk.
• loadSettings(): Loads settings from disk.

// Example of manual sync control
await plugin.startSync();
// ... perform operations ...
await plugin.endSync();

The following configuration keys are used by the plugin to manage state and synchronization: