Git Sync

Git Sync provides automated backup functionality for your Octarine workspace, syncing your notes and folders to GitHub or GitLab repositories. This feature operates as a backup service rather than real-time synchronization, ensuring your content is safely stored in version control.

Prerequisites

Git Sync requires Git to be installed on your system:

• Verify by running git -v in Terminal/Powershell.
• Installation: If Git is missing, your system will prompt for automatic installation when you run the verification command
• SSH Setup: Configure SSH keys for GitHub/GitLab authentication
• Passphrase Storage: Save SSH key passphrases to enable automated syncing without password prompts. This is essential for Git Sync to function properly

Setting Up Git Sync

Git Sync can be configured in two ways:

Manual Setup

• Create Repository: Start with a new, empty repository on GitHub or GitLab to avoid merge conflicts during beta
• Copy SSH URL: After creating the repository, copy the SSH URL (format: git@github.com:username/repository.git)
• Configure in Octarine: Navigate to Settings → Git Sync and paste the SSH URL
• Complete Setup: Click "Finish Setup" to initialize the connection

Automatic Setup

• Git-Enabled Folders: When creating a workspace from a folder that already contains git configurations (such as folders cloned with git clone), Git Sync is automatically configured
• No Additional Setup: The existing git remote is detected and used without manual configuration

Octarine will perform an initial backup of all current files, excluding attachments by default to manage storage usage.

Configuration Options

After setup, the Git Sync preferences screen allows you to customize backup behavior:

• Automated Backups: Toggle periodic backups on or off
• Sync Interval: Set the frequency for backup checks (default: 10 minutes)
• Content Exclusions: Choose whether to exclude:
  • Attachments (excluded by default due to potential size)
  • Templates
  • Files (excluded by default due to potential size)
• Remove Integration: Disconnect the workspace from Git and remove version control

Monitoring Sync Status

The sync status is visible through visual indicators in the interface:

• Cloud Icon: Located in the top-right breadcrumb area
  • Hover to view the last successful sync timestamp
  • Normal appearance indicates successful synchronization
• Warning Icon: Replaces the cloud icon when sync errors occur
  • Hover to see specific error details
  • Manual intervention may be required to resolve Git-related issues
  • Will show up when Auto Sync is turned off.

Whenever an error does occur, auto sync is turned off. Octarine tries to retry syncing 3 times before it turns auto sync off and shows the warning icon.

Sync Behavior

Git Sync operates with these characteristics:

• Automatic Operation: Runs in the background at configured intervals
• Initial Pull: When the app loads or when manually reloaded, a pull is triggered to fetch latest changes from the remote repository
• File Coverage: Backs up all markdown files and folder structure
• Exclusions: Attachments, Files or templates can be optionally excluded
• Repository Structure: Maintains your exact workspace folder hierarchy in the Git repository
• Manual Sync: You can force sync by either Cmd/Ctrl + K → Sync Now or head over to Settings → GitSync and press the Sync Now button.

Conflict Resolution

Git Sync provides automatic conflict resolution when local and remote changes conflict:

• Conflict Resolution Settings: Located in Settings → Git Sync → Conflict Resolution
• Resolution Options:
  • Use Remote Changes: The app favors incoming changes from the remote repository. Remote always wins
  • Keep Local Changes: The app favors your current local changes. Local always wins
• Automatic Handling: Based on your selected preference, conflicts are resolved automatically during sync operations
• No Manual Intervention: Unlike traditional Git workflows, conflicts are handled according to your predefined preference

Troubleshooting

Common issues and their resolutions:

• SSH Authentication Failures: Ensure SSH keys are properly configured and passphrases are saved
• Merge Conflicts: Start with empty repositories during beta to avoid conflicts
• Sync Errors: Check the warning icon for specific error messages
• Repository Access: Verify you have write permissions to the target repository

For complex Git-related issues, knowledge of Git commands may be helpful for manual resolution through Terminal.