gdrive-sync

A CLI tool for bidirectional file synchronization between a local folder and Google Drive.

Features

• Bidirectional sync — detects changes on both sides using a three-way diff algorithm
• Watch mode — monitors local filesystem changes and polls Drive automatically
• Conflict detection — interactive resolution or force local-wins with --force
• Google Docs support — exports Docs/Sheets/Slides to .docx/.xlsx/.pptx locally
• Dry-run mode — preview changes before executing
• SQLite state tracking — reliable change detection across sync runs
• Graceful shutdown — Ctrl+C finishes the current operation before exiting

Installation

go install github.com/SaqrWare/gdrive-sync@latest

Or build from source:

git clone https://github.com/SaqrWare/gdrive-sync.git
cd gdrive-sync
go build -o gdrive-sync .

Prerequisites

1. Create a Google Cloud project at console.cloud.google.com
2. Enable the Google Drive API
3. Create an OAuth 2.0 Client ID (application type: Desktop app)
4. Download the credentials JSON file

Usage

Initialize

gdrive-sync init --credentials /path/to/credentials.json

This will:

• Open your browser for Google OAuth2 authentication
• Prompt for the local folder path and Drive folder name/ID
• Save configuration to ~/.config/gdrive-sync/config.toml

Sync

Run a one-time sync:

gdrive-sync sync

Preview changes without executing:

gdrive-sync sync --dry-run

Sync in one direction only:

gdrive-sync sync --direction up    # local → Drive
gdrive-sync sync --direction down  # Drive → local

Resolve all conflicts with local version:

gdrive-sync sync --force

Watch mode

Continuously monitor and sync:

gdrive-sync watch

Customize polling and debounce intervals:

gdrive-sync watch --poll 1m --debounce 5s

Status

Show pending changes:

gdrive-sync status
gdrive-sync status --json

Logout

Remove cached OAuth token:

gdrive-sync logout
gdrive-sync logout --revoke  # also revoke with Google

Configuration

Config file: ~/.config/gdrive-sync/config.toml

local_path = "/home/user/my-drive-folder"
remote_folder_id = "1ABC..."
remote_folder_name = "My Folder"
delete_mode = "trash"           # "trash" or "permanent"
google_docs_mode = "export_readonly"  # "export_readonly" or "skip"
exclude = ["*.tmp", ".git"]

[export]
"application/vnd.google-apps.document" = "application/vnd.openxmlformats-officedocument.wordprocessingml.document"
"application/vnd.google-apps.spreadsheet" = "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"
"application/vnd.google-apps.presentation" = "application/vnd.openxmlformats-officedocument.presentationml.presentation"

How sync works

The sync engine uses a three-way diff comparing:

1. Local filesystem — current state of files on disk
2. Google Drive — current state of files in the remote folder
3. Sync state database — snapshot from the last successful sync (stored in SQLite)

This allows accurate detection of which side changed, including deletions. Conflicts are raised when both sides changed since the last sync.

License

MIT