gdrive-syncer 2.2.0 → 3.1.0

package/Readme.md

@@ -4,15 +4,54 @@ A command line tool to manage sync folders with Google Drive. Features two-way s
 
 ## Prerequisites
 
-Install and setup [gdrive](https://github.com/prasmussen/gdrive)
+Install the gdrive CLI. This tool supports both gdrive@2 and gdrive@3.
 
-## Login
+### Option 1: gdrive@3 (recommended)
+
+Install [gdrive@3](https://github.com/glotlabs/gdrive) via Homebrew:
+
+```bash
+brew install gdrive
+```
+
+Setup requires Google OAuth credentials.
+
+> **Before you start:** Ask your team if someone already has OAuth credentials set up for gdrive. Sharing existing credentials avoids creating duplicate Google Cloud projects and simplifies onboarding.
+
+#### Setting up OAuth credentials
+
+1. Go to [Google Cloud Console](https://console.cloud.google.com/)
+2. Create a new project or select existing
+3. Enable the Google Drive API
+4. Configure OAuth consent screen:
+   - **For organizations (Google Workspace):** Select **Internal** user type. This avoids the app review process and allows immediate use by your team.
+   - **For personal accounts:** Select **External** and add your email as a test user.
+5. Create OAuth 2.0 credentials (Desktop application)
+6. Add an account:
+   ```bash
+   gdrive account add
+   ```
+7. Enter your Client ID and Client Secret when prompted
+8. Complete the OAuth flow in your browser
+
+> **Tip:** If you're in an organization, using **Internal** OAuth consent means the app is automatically trusted for all users in your domain—no verification required.
+
+**Note:** gdrive@3 does not support `gdrive sync` commands. Use the `filesync:*` commands instead.
+
+### Option 2: gdrive@2 (legacy)
+
+[gdrive@2](https://github.com/prasmussen/gdrive) is deprecated and no longer available via Homebrew. If you have it installed, login with:
 
-After [gdrive](https://github.com/prasmussen/gdrive) is installed, login to your Google Drive account:
 ```bash
 gdrive about
 ```
 
+### Verify Installation
+
+```bash
+gdrive version
+```
+
 ## Installation
 
 ```bash
@@ -33,14 +72,15 @@ Run without arguments for interactive menu, or use direct commands.
 
 | Command | Description |
 |---------|-------------|
-| `filesync:diff [local\|global]` | Show differences between local and Drive |
-| `filesync:download [local\|global]` | Download changed files from Drive |
-| `filesync:upload [local\|global]` | Upload changed files to Drive |
+| `filesync:diff [local\|global\|registered]` | Show differences between local and Drive |
+| `filesync:download [local\|global\|registered]` | Download changed files from Drive |
+| `filesync:upload [local\|global\|registered]` | Upload changed files to Drive |
 | `filesync:init` | Create or add to `.gdrive-sync.json` config |
 | `filesync:show` | Show sync configurations |
 | `filesync:remove` | Remove a sync from config |
 | `filesync:register` | Register local config to global registry |
 | `filesync:unregister` | Remove from global registry |
+| `filesync:migrate` | Migrate legacy syncs to Files Sync format |
 
 ### Drive Operations
 
@@ -51,7 +91,9 @@ Run without arguments for interactive menu, or use direct commands.
 | `drive:mkdir` | Create a directory in Drive |
 | `drive:delete` | Delete a file/folder from Drive |
 
-### Legacy Sync (gdrive sync upload)
+### Legacy Sync (gdrive@2 only)
+
+**Note:** These commands require gdrive@2. They are not available with gdrive@3.
 
 | Command | Description |
 |---------|-------------|
@@ -174,15 +216,35 @@ Patterns support glob-style matching with the following features:
 
 ### Features
 
+- **Nested folder support** - Recursively syncs files in subdirectories
 - **Multiple sync folders** - Configure multiple sync pairs in one config
 - **Local & Global configs** - Per-project or machine-wide configurations
-- **File patterns** - Filter files by pattern
+- **File patterns** - Filter files by pattern (applied to filenames, not paths)
 - **Auto-discovery** - Finds local config in current or parent directories
-- **Git-style diffs** - Colored diff output showing changes
-- **Automatic backups** - Creates timestamped backups before download
+- **Git-style diffs** - Colored diff output showing changes with full paths
+- **Automatic backups** - Creates timestamped backups before download (preserves folder structure)
 - **Two-way sync** - Upload local changes or download from Drive
+- **Optional deletion** - Prompts to delete orphan files/folders after sync
 - **Sync All** - Run operations on all syncs within selected config
 - **Registered Local Configs** - Run sync on multiple projects from anywhere
+- **Auto-create folders** - Creates missing folders on Drive during upload
+
+### Sync Behavior
+
+The sync compares files between local and Drive, showing:
+
+| Status | Diff | Upload | Download |
+|--------|------|--------|----------|
+| **Modified** | Shows diff | Updates on Drive | Updates locally |
+| **Local only** | Listed | Uploads to Drive | Prompts to delete |
+| **Drive only** | Listed | Prompts to delete | Downloads locally |
+| **Empty folders** | Listed | Prompts to delete | — |
+
+**Delete prompts:**
+- **Upload**: After uploading, prompts to delete files/folders on Drive that don't exist locally
+- **Download**: After downloading, prompts to delete local files that don't exist on Drive (backup is created first)
+
+This ensures you can keep Drive in sync with local (or vice versa) without accumulating orphan files.
 
 ### Registered Local Configs
 
@@ -213,7 +275,9 @@ gdrive-syncer filesync:diff
 4. Multi-select which projects to sync
 5. Operation runs on all selected projects
 
-## Legacy Sync Configuration
+## Legacy Sync Configuration (gdrive@2 only)
+
+> **Note:** Legacy sync requires gdrive@2. If you have gdrive@3 installed, use Files Sync (`filesync:*` commands) instead.
 
 Legacy sync uses the `gdrive sync upload` command under the hood. Configuration is stored globally at:
 
@@ -287,10 +351,30 @@ gdrive-syncer sync:upload
 gdrive-syncer sync:list
 ```
 
+## Migrating from Legacy Sync to Files Sync
+
+If you have existing legacy sync configurations (`~/.gdrive_syncer/gdrive.config.json`), you can migrate them to the new Files Sync format:
+
+```bash
+gdrive-syncer filesync:migrate
+```
+
+The migration wizard:
+1. Shows all legacy syncs and lets you select which to migrate
+2. For each sync, asks whether to save to **Local** or **Global** config
+3. For local configs, calculates the relative path from the config location
+4. Warns if the path is outside the project directory (suggests using global instead)
+5. Lets you set a file pattern (default: `*` for all files)
+6. Shows a preview before confirming
+7. Optionally removes migrated syncs from the legacy config
+
+This is not a one-time migration—you can run it multiple times to gradually migrate syncs as needed.
+
 ## Files Sync vs Legacy Sync
 
 | Feature | Files Sync | Legacy Sync |
 |---------|----------|-------------|
+| **gdrive version** | gdrive@2 and gdrive@3 | gdrive@2 only |
 | Config location | Local (`.gdrive-sync.json`) or Global (`~/.gdrive_syncer/env-sync.json`) | `~/.gdrive_syncer/gdrive.config.json` (global only) |
 | Direction | Two-way (upload & download) | One-way (upload only) |
 | File patterns | Supported (`.env.*`, `*`) | All files in folder |
@@ -318,6 +402,9 @@ gdrive-syncer filesync:diff local
 # Show differences for global config only
 gdrive-syncer filesync:diff global
 
+# Show differences for registered local configs
+gdrive-syncer filesync:diff registered
+
 # Download from Drive (with backup)
 gdrive-syncer filesync:download
 gdrive-syncer filesync:download local
@@ -326,6 +413,9 @@ gdrive-syncer filesync:download local
 gdrive-syncer filesync:upload
 gdrive-syncer filesync:upload global
 
+# Upload from all registered configs
+gdrive-syncer filesync:upload registered
+
 # Initialize config (choose Local or Global)
 gdrive-syncer filesync:init
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gdrive-syncer",
-  "version": "2.2.0",
+  "version": "3.1.0",
   "description": "Google Drive Syncer",
   "main": "./index.js",
   "bin": "./run.js",

package/run.js

@@ -5,15 +5,15 @@ const color = require('picocolors');
 const { cfgAdd, cfgRm, cfgShow } = require('./src/cfgManager');
 const { runSync } = require('./src/sync');
 const { runList, runSearch, runDelete, runMkdir, runListSync } = require('./src/list');
-const { envInit, envRun, envShow, envRemove, envRegister, envUnregister } = require('./src/envSync');
+const { envInit, envRun, envShow, envRemove, envRegister, envUnregister, envMigrate } = require('./src/envSync');
 
 const [, , ...args] = process.argv;
 const [firstArg] = args;
 
-// Get config type from args (local/global)
+// Get config type from args (local/global/registered)
 const getConfigType = () => {
   const arg = args[1]?.toLowerCase();
-  if (arg === 'local' || arg === 'global') return arg;
+  if (arg === 'local' || arg === 'global' || arg === 'registered') return arg;
   return null;
 };
 
@@ -29,6 +29,7 @@ const commands = {
   'filesync:remove': { handler: envRemove, desc: 'Remove sync config' },
   'filesync:register': { handler: envRegister, desc: 'Register local config to global' },
   'filesync:unregister': { handler: envUnregister, desc: 'Unregister local config' },
+  'filesync:migrate': { handler: envMigrate, desc: 'Migrate legacy syncs to Files Sync' },
 
   // Drive Operations
   'drive:search': { handler: runSearch, desc: 'Search files in Drive' },
@@ -49,14 +50,15 @@ const showHelp = () => {
   const lines = [
     `${color.bold('Files Sync')} ${color.dim('(two-way sync with .gdrive-sync.json)')}`,
     `  filesync                  ${color.dim('Interactive sync menu')}`,
-    `  filesync:diff [local|global]   ${color.dim('Show differences')}`,
-    `  filesync:download [local|global] ${color.dim('Download from Drive')}`,
-    `  filesync:upload [local|global]   ${color.dim('Upload to Drive')}`,
+    `  filesync:diff [local|global|registered]   ${color.dim('Show differences')}`,
+    `  filesync:download [local|global|registered] ${color.dim('Download from Drive')}`,
+    `  filesync:upload [local|global|registered]   ${color.dim('Upload to Drive')}`,
     `  filesync:init             ${color.dim('Create/add sync config')}`,
     `  filesync:show             ${color.dim('Show configurations')}`,
     `  filesync:remove           ${color.dim('Remove sync config')}`,
     `  filesync:register         ${color.dim('Register local config to global')}`,
     `  filesync:unregister       ${color.dim('Unregister local config')}`,
+    `  filesync:migrate          ${color.dim('Migrate legacy syncs to Files Sync')}`,
     ``,
     `${color.bold('Drive Operations')}`,
     `  drive:search  ${color.dim('Search files')}`,
@@ -136,6 +138,7 @@ const showHelp = () => {
           { value: 'filesync:remove', label: 'Remove', hint: 'Remove a sync from config' },
           { value: 'filesync:register', label: 'Register', hint: 'Register local config to global' },
           { value: 'filesync:unregister', label: 'Unregister', hint: 'Unregister local config' },
+          { value: 'filesync:migrate', label: 'Migrate', hint: 'Migrate legacy syncs to Files Sync' },
         ],
       });
     } else if (category === 'drive') {
@@ -158,6 +161,7 @@ const showHelp = () => {
           { value: 'sync:show', label: 'Show Config', hint: 'View sync configurations' },
           { value: 'sync:add', label: 'Add Config', hint: 'Add a new sync configuration' },
           { value: 'sync:remove', label: 'Remove Config', hint: 'Remove a sync configuration' },
+          { value: 'filesync:migrate', label: 'Migrate to Files Sync', hint: 'Migrate to new format' },
         ],
       });
     }