Auto Sync - Auk Documentation

Overview

Auto sync automatically synchronizes your workspace with the remote Git repository at regular intervals, ensuring your team always has the latest changes.

Automatic Commits

Changes are automatically committed to local Git

Scheduled Sync

Push and pull at configurable intervals

Conflict Detection

Automatically detects and handles merge conflicts

Background Operation

Syncs in background without interrupting work

Enable Auto Sync

Via Workspace Settings

Open Settings

Navigate to Workspace Settings → Git Sync

Enable Auto Sync

Toggle “Automatic Synchronization” to ON

Configure Interval

Choose sync interval (default: 15 minutes)

Save Settings

Changes are applied immediately

Via Configuration File

Edit workspace settings.json:

{
  "git": {
    "enabled": true,
    "remoteUrl": "[email protected]:username/api-collections.git",
    "autoSync": true,
    "syncInterval": 900,
    "autoCommit": true,
    "syncBeforeSwitch": true
  }
}

Sync Intervals

Choose an interval based on your collaboration needs:

Active Collaboration
Balanced (Default)
Periodic Updates
Manual Only

5 minutes - For teams actively working together

{
  "git": {
    "syncInterval": 300
  }
}

Best for:

Real-time collaboration
Pair programming
Rapid iteration
Small teams

Considerations:

Higher network usage
More frequent conflict checks
Battery impact on laptops

15 minutes - Balanced approach for most teams

{
  "git": {
    "syncInterval": 900
  }
}

Best for:

Regular team collaboration
Distributed teams
Most use cases

Considerations:

Good balance of freshness and efficiency
Reasonable network usage
Minimal battery impact

1 hour - For less frequent collaboration

{
  "git": {
    "syncInterval": 3600
  }
}

Best for:

Solo work with occasional sync
Slow-moving projects
Limited network connectivity

Considerations:

Lower network usage
Minimal battery impact
May miss recent changes

Disabled - Full manual control

{
  "git": {
    "autoSync": false
  }
}

Best for:

Complete control over sync timing
Unstable network connections
Solo projects

Considerations:

Must remember to sync manually
Risk of conflicts if forgotten
No automatic backups

Sync Behavior

Automatic Commit

When auto-commit is enabled, Auk automatically commits changes:

{
  "git": {
    "autoCommit": true,
    "commitMessageTemplate": "Update {{collection}} - {{timestamp}}"
  }
}

Commit triggers:

After saving a collection
After modifying an environment
After deleting items
Before sync operation

Example commit message:

Update User API collection

- Added POST /users endpoint
- Modified GET /users/:id response
- Updated development environment

Co-Authored-By: Auk <[email protected]>

Sync Process

Each sync operation follows this flow:

Pre-Sync Check

Check if Git is enabled
Verify network connectivity
Ensure no conflicts from previous sync

Commit Local Changes

Stage all modified files
Create commit with descriptive message
Update local Git repository

Pull Remote Changes

Fetch from remote repository
Merge remote changes into local branch
Detect conflicts if any

Conflict Resolution

If conflicts detected, pause sync
Notify user and show conflict UI
Wait for user resolution

Push Local Changes

Push committed changes to remote
Update remote branch
Verify push success

Post-Sync

Update sync status indicator
Log sync result
Schedule next sync

Sync Triggers

Auto sync can be triggered by multiple events:

Time-Based (Primary)

Sync at regular intervals:

{
  "git": {
    "syncInterval": 900  // Every 15 minutes
  }
}

Event-Based

Sync on specific events:

syncBeforeSwitch

boolean

default:"true"

Sync before switching workspaces

{
  "git": {
    "syncBeforeSwitch": true
  }
}

syncOnStartup

boolean

default:"true"

Sync when opening workspace

{
  "git": {
    "syncOnStartup": true
  }
}

syncOnClose

boolean

default:"true"

Sync before closing Auk

{
  "git": {
    "syncOnClose": true
  }
}

Manual Trigger

Always available regardless of auto-sync settings:

Click sync button in toolbar
Keyboard shortcut: Cmd/Ctrl + Shift + S
Right-click workspace → “Sync Now”

Sync Status Indicator

Monitor sync status in real-time:

🟢 Synced              - Up to date with remote
🟡 Syncing...          - Sync in progress
🟠 3 changes pending   - Local changes not yet synced
🔴 Sync failed         - Error occurred
⚠️  Conflict detected  - Manual resolution needed
⏸️  Sync paused        - Auto-sync temporarily disabled

Status Details

Click the status indicator to see:

Last sync time
Pending changes count
Sync history
Error messages (if any)

Conflict Handling

When conflicts are detected during auto-sync:

Automatic Resolution

Configure automatic conflict resolution:

{
  "git": {
    "conflictResolution": "prompt"
  }
}

Options:

Prompt (Default)
Keep Local
Use Remote
Smart Merge

{
  "conflictResolution": "prompt"
}

Pause sync when conflict detected
Show conflict resolution UI
Wait for user decision
Resume sync after resolution

{
  "conflictResolution": "keepLocal"
}

Automatically keep local changes
Discard remote changes
Continue sync without interruption

May overwrite team members’ changes

{
  "conflictResolution": "useRemote"
}

Automatically use remote changes
Discard local changes
Continue sync without interruption

May lose your local changes

{
  "conflictResolution": "smartMerge"
}

Attempt automatic merge
Keep non-conflicting changes from both
Prompt only for unresolvable conflicts

Conflict Notification

When conflicts occur:

Desktop Notification - System notification appears
Status Indicator - Shows conflict warning
Conflict Panel - Opens automatically (if configured)
Sync Paused - Auto-sync pauses until resolved

Network Considerations

Offline Handling

When network is unavailable:

Auto-sync gracefully fails
Changes continue to commit locally
Sync resumes when network returns
No data loss

{
  "git": {
    "offlineMode": "queue",  // Queue syncs for later
    "retryAttempts": 3,
    "retryDelay": 60
  }
}

Bandwidth Optimization

For limited bandwidth:

{
  "git": {
    "syncInterval": 3600,        // Sync less frequently
    "compressTransfer": true,    // Enable Git compression
    "shallowClone": true         // Shallow clone (no full history)
  }
}

Performance Optimization

Large Repositories

For workspaces with many collections:

{
  "git": {
    "incrementalSync": true,     // Only sync changed files
    "parallelSync": false,       // Disable parallel operations
    "syncTimeout": 300           // Increase timeout to 5 minutes
  }
}

Battery Saving

For laptop users:

{
  "git": {
    "syncInterval": 3600,        // Sync hourly
    "pauseOnBattery": true,      // Pause when on battery
    "batteryThreshold": 20       // Resume when > 20%
  }
}

Monitoring and Logs

Sync History

View sync history:

Recent Syncs:
├── 2024-02-20 14:30 - Success (3 files changed)
├── 2024-02-20 14:15 - Success (1 file changed)
├── 2024-02-20 14:00 - Conflict resolved
└── 2024-02-20 13:45 - Success (no changes)

Sync Logs

Enable detailed logging:

{
  "git": {
    "enableLogging": true,
    "logLevel": "info",          // debug, info, warn, error
    "logFile": "~/Library/Logs/Auk/git-sync.log"
  }
}

View logs:

# macOS
tail -f ~/Library/Logs/Auk/git-sync.log

# Windows
type %APPDATA%\Auk\Logs\git-sync.log

# Linux
tail -f ~/.config/Auk/logs/git-sync.log

Best Practices

Choose Appropriate Interval

Match sync interval to collaboration intensity:

Active team: 5-15 minutes
Regular collaboration: 15-30 minutes
Solo work: 1 hour or manual

Enable Sync Before Switch

Always sync before switching workspaces to avoid conflicts:

{
  "git": {
    "syncBeforeSwitch": true
  }
}

Monitor Sync Status

Regularly check sync status indicator:

Ensure syncs are completing successfully
Address conflicts promptly
Verify network connectivity

Handle Conflicts Quickly

Don’t let conflicts accumulate:

Resolve conflicts as soon as detected
Communicate with team about major changes
Use feature branches for large modifications

Test Auto-Sync Setup

Verify auto-sync is working:

Make a small change
Wait for sync interval
Check remote repository
Verify change appears

Troubleshooting

Auto-sync not working

Symptoms: Changes not syncing automaticallySolutions:

Verify auto-sync is enabled in settings
Check network connectivity
Review sync logs for errors
Ensure Git authentication is valid

Sync takes too long

Symptoms: Sync operations are slowSolutions:

Increase sync interval
Enable compression
Check network speed
Consider shallow clone for large repos

Frequent conflicts

Symptoms: Conflicts on every syncSolutions:

Reduce sync interval for more frequent updates
Coordinate with team on who edits what
Use feature branches
Enable smart merge

High battery drain

Symptoms: Laptop battery drains quicklySolutions:

Increase sync interval
Enable battery-saving mode
Disable sync when on battery
Use manual sync when needed

Next Steps

Conflict Resolution

Learn how to resolve merge conflicts

Troubleshooting

Solve common sync issues

Branch Management

Work with Git branches (coming soon)

Workspace Settings

Configure all workspace options

Getting Started

Core Concepts

Workspace Management

Git Sync

API Testing

Features

Data Management

Desktop Client

​Overview

Automatic Commits

Scheduled Sync

Conflict Detection

Background Operation

​Enable Auto Sync

​Via Workspace Settings

​Via Configuration File

​Sync Intervals

​Sync Behavior

​Automatic Commit

​Sync Process

​Sync Triggers

​Time-Based (Primary)

​Event-Based

​Manual Trigger

​Sync Status Indicator

​Status Details

​Conflict Handling

​Automatic Resolution

​Conflict Notification

​Network Considerations

​Offline Handling

​Bandwidth Optimization

​Performance Optimization

​Large Repositories

​Battery Saving

​Monitoring and Logs

​Sync History

​Sync Logs

​Best Practices

​Troubleshooting

​Next Steps

Conflict Resolution

Troubleshooting

Branch Management

Workspace Settings

Overview

Enable Auto Sync

Via Workspace Settings

Via Configuration File

Sync Intervals

Sync Behavior

Automatic Commit

Sync Process

Sync Triggers

Time-Based (Primary)

Event-Based

Manual Trigger

Sync Status Indicator

Status Details

Conflict Handling

Automatic Resolution

Conflict Notification

Network Considerations

Offline Handling

Bandwidth Optimization

Performance Optimization

Large Repositories

Battery Saving

Monitoring and Logs

Sync History

Sync Logs

Best Practices

Troubleshooting

Next Steps