Git Sync Overview

​

What is Git Sync?

​

Why Git Instead of Cloud?

​

Full Control

• GitHub (public or private)
• GitLab (self-hosted or cloud)
• Bitbucket
• Gitee (Chinese service)
• Your own Git server
• Company internal Git

​

Standard Workflows

• Branches for feature development
• Pull requests for code review
• Merge strategies for conflict resolution
• Tags for versioning
• Git history for auditing

​

No Vendor Lock-in

• Not tied to specific cloud provider
• Easy migration between Git services
• Standard Git format
• Open source tools

​

Privacy & Security

• Choose public or private repositories
• Self-host for complete privacy
• Encryption at rest and in transit
• Access control via Git permissions

​

How It Works

​

Architecture

┌─────────────────┐
│  Local Auk App  │
│                 │
│  ┌───────────┐  │
│  │Workspace  │  │
│  │  Data     │  │
│  └─────┬─────┘  │
│        │        │
│   ┌────▼────┐   │
│   │Local Git│   │
│   │  Repo   │   │
│   └────┬────┘   │
└────────┼────────┘
         │
    ┌────▼────┐
    │ Network │
    └────┬────┘
         │
┌────────▼────────┐
│  Remote Git     │
│  Repository     │
│  (GitHub, etc.) │
└────────┬────────┘
         │
    ┌────▼────┐
    │ Network │
    └────┬────┘
         │
┌────────▼────────┐
│  Team Member's  │
│  Auk App        │
└─────────────────┘

​

Sync Process

​

Key Features

​

Automatic Synchronization

• Configure sync interval (5min to 60min)
• Automatic commit of local changes
• Automatic pull and push
• Background operation

• Disable auto-sync if preferred
• Manual “Sync Now” button
• Review changes before pushing
• Selective syncing

​

Conflict Detection

• Detects when same file modified by multiple people
• Shows clear conflict indicators
• Provides resolution options
• Preserves both versions for review

• Keep local changes
• Use remote changes
• Manual merge
• Smart merge (auto-resolve when possible)

​

Branch Support

• Create feature branches
• Switch between branches
• Merge branches
• Delete branches

• Experimental changes
• Large refactoring
• Team feature development
• Environment-specific branches

​

History & Rollback

• Complete change history
• View diffs between versions
• Rollback to previous state
• Blame/annotate changes

• Who made changes
• When changes were made
• What was changed
• Why (commit messages)

​

Supported Git Services

​

GitHub

• Public and private repositories
• Organization support
• OAuth authentication
• Pull requests
• Actions for CI/CD

# SSH
[email protected]:username/repo.git

# HTTPS
https://github.com/username/repo.git

​

GitLab

• Self-hosted or GitLab.com
• Built-in CI/CD
• Container registry
• Issue tracking

# SSH
[email protected]:username/repo.git

# HTTPS
https://gitlab.com/username/repo.git

​

Bitbucket

• Atlassian integration
• Jira integration
• Pipelines for CI/CD
• Code review

# SSH
[email protected]:username/repo.git

# HTTPS
https://bitbucket.org/username/repo.git

​

Self-Hosted Git

• GitLab CE (Community Edition)
• Gitea (lightweight)
• Gogs (simple)
• Gitolite (minimal)

# SSH
[email protected]:repo.git

# HTTPS
https://your-server.com/repo.git

​

Authentication Methods

​

SSH Keys (Recommended)

• No password needed
• More secure
• Works with all Git services
• Easy to manage

# Generate key
ssh-keygen -t ed25519 -C "[email protected]"

# Add to SSH agent
ssh-add ~/.ssh/id_ed25519

# Copy public key
cat ~/.ssh/id_ed25519.pub

​

HTTPS with Token

• Works through firewalls
• No SSH setup needed
• Easy to revoke

1. Generate personal access token
2. Use token as password
3. Save in credential manager

​

OAuth (Coming Soon)

• No manual token management
• Automatic refresh
• Revocable access

• GitHub OAuth
• GitLab OAuth

​

Data Synced

​

Collections

collections/
├── rest/
│   ├── users-api.json
│   ├── products-api.json
│   └── orders-api.json
├── graphql/
│   └── main-api.json
└── realtime/
    └── websocket-api.json

​

Environments

environments/
├── development.json
├── staging.json
└── production.json

​

Settings

settings.json

​

Not Synced

• History - Request history stays local
• Secrets - Secret environment variables
• Local State - UI state, window position, etc.
• Cache - Temporary data

​

Sync Modes

​

Auto Sync

• Runs at configured interval
• Automatic commit and push
• Background operation
• Minimal user interaction

{
  "autoSync": true,
  "syncInterval": 300,  // 5 minutes
  "syncOnChange": true
}

​

Manual Sync

• Click “Sync Now” button
• Keyboard shortcut: Cmd/Ctrl + Shift + S
• Review changes before pushing
• More control over timing

• Sensitive changes
• Large refactoring
• Experimental work
• Offline work

​

Hybrid Mode

• Auto-commit locally
• Manual push to remote
• Review before sharing
• Automatic pull from remote

​

Conflict Resolution

​

When Conflicts Occur

• Same file modified by multiple people
• Changes made offline by different team members
• Concurrent edits to same collection

​

Resolution Process

​

Resolution Strategies

• Use your changes
• Discard remote changes
• Fast and simple
• Risk: lose team changes

• Use team changes
• Discard your changes
• Fast and simple
• Risk: lose your work

• Automatic merge when possible
• Combines both changes
• Works for non-overlapping changes
• May still need manual review

• Review both versions
• Choose what to keep
• Edit directly if needed
• Most control, most time

​

Best Practices

​

Commit Messages

✅ Good (auto-generated):
"Update users-api: Added new endpoint GET /users/:id"
"Update development environment: Changed API_URL"
"Add new collection: Products API"

❌ Bad:
"Update"
"Changes"
"WIP"

​

Sync Frequency

​

Branch Strategy

• Stable, tested collections
• Production-ready
• Protected from direct pushes

• New API endpoints
• Experimental changes
• Large refactoring

• dev - Development
• staging - Staging
• prod - Production

​

Communication

• Notify team
• Create feature branch
• Document changes
• Request review

• Sync immediately
• Notify team
• Update documentation
• Test thoroughly

​

Troubleshooting

​

Common Issues

• Check SSH keys or token
• Verify permissions
• Test Git connection

• Pull latest changes first
• Resolve conflicts
• Try again

• Check network connection
• Reduce sync frequency
• Use shallow clone

• Archive old collections
• Split into multiple workspaces
• Use Git LFS for large files

​

Next Steps