Git Sync Setup Guide

Synchronize your Lokus workspace across unlimited devices for free using Git. This guide covers the complete setup process with the redesigned sync system introduced in v1.3.4.

Overview

The new sync system simplifies configuration from 6 fields down to 3 essential fields:

Key Improvements:

• Unified Token System: One token field instead of confusing dual-token setup
• Auto-generated Email: No need to manually enter email address
• Better Error Messages: Clear, actionable feedback on what went wrong
• Conflict Resolution UI: Visual tools for resolving merge conflicts
• Connection Testing: Verify credentials before saving

Prerequisites

Before setting up sync, you’ll need:

1. A Git provider account (GitHub, GitLab, Bitbucket, etc.)
2. A private repository to store your workspace
3. A personal access token with repository access
4. Internet connection for initial setup

Step 1: Create a Private Repository

Step 2: Create a Personal Access Token

Git providers require a token for authentication. This is more secure than using your password.

Step 3: Configure Lokus Sync

Now configure sync in your Lokus workspace with the simplified 3-field setup.

Step 4: First Sync

Perform your first sync to upload your workspace to the remote repository.

Option 1: Automatic Sync (Recommended)

1. Make any change to a note (type something and save)
2. The sync status indicator turns yellow ⚡ (changes pending)
3. Click the status indicator
4. Lokus commits and pushes your workspace automatically

Option 2: Manual Sync

1. Right-click the sync status indicator (bottom-right)
2. Select “Commit & Push” from the menu
3. Your workspace is uploaded to the remote repository

Verify on Remote

Check your Git provider to confirm files were uploaded:

1. Go to your repository on GitHub/GitLab/Bitbucket
2. You should see all your workspace files
3. Commit message: “Auto-sync workspace” or “Initial commit”

Step 5: Setup on Additional Devices

To sync the same workspace on another device:

Understanding Sync Status

The sync indicator (bottom-right corner) shows the current status:

Click Actions

• Left-click: Quick commit & push (if changes pending)
• Right-click: Open sync menu with more options:
  • Pull Changes
  • Commit & Push
  • Check Status
  • Force Push (dangerous!)
  • Force Pull (dangerous!)

Conflict Resolution

When two devices modify the same file differently, conflicts occur.

Detecting Conflicts

Lokus shows conflicts with:

• ⚠️ Orange warning icon
• Status text: “2 conflicts”
• Notification: “Merge conflicts detected”

Viewing Conflicts

1. Right-click the sync status indicator
2. The menu shows conflicted files:

   ⚠️ 2 Conflicts Detected
   
   meeting-notes.md
   project-plan.md

Resolving Conflicts

<<<<<<< Your Changes (Local)
# Meeting Notes - November 6th
=======
# Team Meeting - Nov 6
>>>>>>> Remote Changes

Conflict Prevention

To minimize conflicts:

• Sync frequently: Pull changes before making major edits
• One device at a time: Avoid editing the same file on multiple devices simultaneously
• Communicate: If collaborating, coordinate who edits what

Force Resolution (Last Resort)

If conflicts are too complex, use force options:

Force Push (Keep Local):

• Overwrites remote with your local version
• ⚠️ Destroys remote changes permanently
• Use only if remote changes are unwanted

Force Pull (Keep Remote):

• Overwrites local with remote version
• ⚠️ Destroys your local changes permanently
• Use only if local changes are unwanted

Sync Menu Reference

Right-click the sync status indicator to access these options:

Pull Changes

• Downloads changes from remote repository
• Merges remote changes with your local workspace
• Safe: Won’t overwrite your uncommitted changes
• When to use: Another device pushed changes

Commit & Push

• Commits your local changes
• Pushes to remote repository
• Makes your changes available to other devices
• When to use: You made changes and want to sync them

Check Status

• Refreshes git status without syncing
• Shows if you’re ahead, behind, or have conflicts
• When to use: Curious about sync state without changing anything

Force Push

• ⚠️ Overwrites remote with local (DESTRUCTIVE)
• Discards all remote changes permanently
• When to use: Remote is corrupted and you want to replace it

Force Pull

• ⚠️ Overwrites local with remote (DESTRUCTIVE)
• Discards all local changes permanently
• When to use: Local is corrupted and you want to reset it

Advanced Configuration

Custom Branch

By default, Lokus uses the main branch. To use a different branch:

1. Go to Settings → Sync
2. Change the Branch field to your preferred branch (e.g., develop, notes)
3. Click Connect Remote Repository to verify

Multiple Workspaces

You can sync multiple workspaces to different repositories:

1. Create separate repositories for each workspace
2. Each workspace has its own sync configuration
3. Switch between workspaces in Lokus (File → Open Workspace)

Sync with Self-Hosted Git

Lokus works with any Git server:

1. Use your Git server’s HTTPS URL
2. Generate access token in your Git server
3. Configure Lokus sync with server URL and token

Examples:

• Gitea: https://git.example.com/user/repo.git
• Gogs: https://gogs.example.com/user/repo.git
• Azure DevOps: https://dev.azure.com/org/project/_git/repo

Troubleshooting

”Authentication Failed”

Cause: Invalid username or token

Solution:

1. Verify username is correct (not email)
2. Generate a new token
3. Ensure token has correct permissions:
   • GitHub: repo scope
   • GitLab: write_repository + read_repository
4. Update token in Settings → Sync

”Repository Not Found”

Cause: Invalid repository URL or permission issue

Solution:

1. Verify repository URL ends with .git
2. Check repository is private (public repos can have different issues)
3. Ensure token has access to the repository
4. Try cloning the repository manually with Git to test credentials

”Network Error”

Cause: Connection issue

Solution:

1. Check internet connection
2. Try accessing Git provider website
3. Verify firewall isn’t blocking Git connections
4. Check if VPN is interfering

”Failed to Push - Non-Fast-Forward”

Cause: Remote has changes you don’t have locally

Solution:

1. Right-click sync status
2. Select Pull Changes first
3. Resolve any conflicts
4. Then Commit & Push

”Git Not Initialized”

Cause: Git repository not set up in workspace

Solution:

1. Go to Settings → Sync
2. Expand “Git Configuration”
3. Click Initialize Git
4. Then click Connect Remote Repository

Sync Indicator Stuck

Cause: Sync operation timed out or crashed

Solution:

1. Restart Lokus
2. Check sync status (right-click indicator → Check Status)
3. If still stuck, go to Settings → Sync → Initialize Git again

Best Practices

1. Sync Frequently

Sync early and often to avoid conflicts:

• Before major editing sessions: Pull Changes
• After making changes: Commit & Push
• When switching devices: Pull Changes first

2. Use Descriptive Commits

When manually committing (via Git command line), use clear commit messages:

git commit -m "Add meeting notes from Q4 planning"

3. Regular Token Rotation

For security, rotate your tokens every 90 days:

1. Generate new token
2. Update in Lokus Settings → Sync
3. Revoke old token in Git provider

4. Backup Strategy

Sync is not a backup! Maintain separate backups:

• Export workspace periodically (File → Export Workspace)
• Use Time Machine (Mac) or File History (Windows)
• Keep critical notes in multiple locations

5. Private Repositories Only

Never sync sensitive notes to public repositories:

• Always use private repositories
• Double-check repository visibility settings
• Audit repository access regularly (who has access?)

6. Monitor Sync Health

Check the sync status indicator regularly:

• Blue ☁️ = Healthy
• Yellow ⚡ = Sync soon
• Orange ⚠️ = Take action
• Red ❌ = Fix immediately

Migrating from Old Sync System

If you set up sync before v1.3.4, follow these steps to migrate:

Security & Privacy

How Tokens Are Stored

• Encrypted: Tokens are encrypted using OS-level encryption (Keychain on Mac, Credential Manager on Windows)
• Local Only: Tokens never leave your device
• No Cloud: Lokus doesn’t send tokens to any external service
• Secure Communication: All Git communication uses HTTPS

Data Privacy

• You Own Your Data: All notes stored in your private Git repository
• No Lokus Servers: Sync goes directly between your device and Git provider
• No Analytics: Lokus doesn’t track what you sync or when
• Open Source: Sync code is open source and auditable

Revoking Access

To revoke sync access:

1. Revoke token in Git provider settings:
   • GitHub: Settings → Developer settings → Personal access tokens → Revoke
   • GitLab: Preferences → Access Tokens → Revoke
   • Bitbucket: Settings → App passwords → Delete
2. Remove from Lokus: Settings → Sync → Clear credentials

Audit Log

Your Git repository maintains a complete history:

• Every sync creates a commit
• View history: git log in workspace folder
• See who changed what and when
• Revert to any previous state if needed

Frequently Asked Questions

Can I sync for free?

Yes! Git sync is completely free with:

• GitHub: Unlimited private repos, unlimited devices
• GitLab: 5GB free storage
• Bitbucket: 1GB free storage

How many devices can I sync?

Unlimited! There’s no device limit. Sync across as many devices as you need.

Does sync work offline?

Partially: You can work offline. Changes are queued locally and sync when you reconnect to the internet.

Can multiple people collaborate on one workspace?

Yes, but carefully:

• All users need repository access
• Set up sync with same repository
• Communicate to avoid conflicts
• Consider using branches for concurrent work

What’s the difference between sync and backup?

Sync: Real-time synchronization across devices. Data lives in Git repository.

Backup: Point-in-time snapshot stored separately. Use both!

Can I sync to Dropbox/Google Drive instead?

No direct integration, but you can:

1. Create workspace folder in Dropbox/Google Drive
2. Dropbox/Drive syncs the folder automatically
3. Not recommended (can corrupt files if editing on multiple devices simultaneously)
4. Git sync is safer and designed for this use case

What happens if my token expires?

Lokus shows an authentication error. Generate a new token and update it in Settings → Sync.

Can I use SSH instead of HTTPS?

Not yet. Current version supports HTTPS only. SSH support is planned for a future release.

Next Steps

Now that sync is set up:

• Conflict Resolution Tutorial - Learn to handle merge conflicts like a pro
• Advanced Sync Workflows - Branch strategies and team collaboration
• Git Sync Feature Page - Complete sync documentation
• Backup Strategies - Protect your data with multiple backups

Need Help?

• Check Troubleshooting section above
• Visit FAQ for common questions
• Join community Discord for support
• Email support: support@lokusmd.com