Git Sync

Git Sync lets Octarine commit workspace changes, pull from a remote, and push to it on a schedule. It is a Git-based backup and synchronization workflow, not real-time collaboration.

Prerequisites

Git Sync requires:

• Git installed on the computer. Run git --version in a terminal to check.
• A remote Git repository that you can access over SSH.
• SSH keys configured for the Git host. GitHub provides an SSH setup guide.
• Any SSH passphrase available to the system credential manager, so background syncs do not stop for an interactive prompt.

For the simplest first setup, use a new empty remote repository.

Setting Up Git Sync

Connect A Remote

1. Create an empty repository on GitHub, GitLab, or another Git host.
2. Copy its SSH URL, such as git@github.com:username/notes.git.
3. Open Settings -> Git Sync.
4. Paste the URL into Remote SSH URL and click Finish Setup.

Octarine initializes Git in the workspace, uses the main branch, creates the initial ignore rules when needed, and performs the first sync.

Existing Git Workspaces

When a workspace folder already contains a Git repository with an origin remote, Octarine detects it and enables Git Sync automatically. This also applies to workspaces created with Import from Git.

What Git Sync Includes

Git follows the workspace's .gitignore. When Octarine creates that file, the default entries are:

/.attachments
/DS_Store
/node_modules
/.templates
/.files
.octarine/embeddings*

This means a new default setup excludes media attachments, external files, templates, common operating-system or dependency files, and the rebuildable embedding database.

Octarine does not ignore the entire .octarine folder. Workspace-owned data such as Inbox captures, property definitions, note types, themes, and AI skills can therefore travel through Git unless you exclude their directories yourself. See Storing Data for the current workspace layout.

If the workspace already has a .gitignore, Octarine preserves its existing rules, removes the obsolete rule that ignored all of /.octarine, and ensures the embeddings rule is present. Review the file before the first push when the repository has custom requirements.

Managing Ignored Directories

Open Settings -> Git Sync -> Ignored to manage directory exclusions without editing .gitignore by hand.

• The left column lists available workspace directories, including Attachments, Files, and Templates.
• Search for a directory, then add it to the ignored list.
• Remove a directory from the right column when it should be included in future commits.
• Ignoring a parent directory also ignores its nested directories.

The screen preserves unrelated .gitignore rules. Removing an ignore rule only makes future changes eligible for Git; it does not erase copies already present in repository history.

Sync Preferences

After setup, Settings -> Git Sync provides:

• Manage Git in Octarine — lets Octarine show Git controls and run commits, pulls, and pushes. Turn it off to leave the repository untouched without deleting .git.
• Auto Sync — enables scheduled synchronization.
• Backup Interval — checks every 1, 2, 3, 5, 10, 15, 30, or 60 minutes. New setups default to 10 minutes.
• Conflict Resolution — choose Keep Local Changes or Use Remote Changes when Git must resolve competing edits.
• Sync Now — immediately runs a sync. You can also run Sync Now from the Command Bar.
• Pull Changes — pulls origin/main without first committing local changes or pushing anything. It is also available from the Command Bar and the Workspace app menu.

When Octarine opens a Git-enabled workspace, it commits pending local changes before pulling remote changes. During normal syncs it stages workspace changes, creates a commit when needed, pulls, and pushes outstanding commits.

If the device is offline, Octarine can commit changes locally and push them after the network returns. Network failures do not turn off Auto Sync. A non-network Git error is recorded and pauses Auto Sync so the repository can be inspected safely.

Use Pull Changes when you only want to bring the remote main branch into the workspace. Unlike Sync Now, it does not stage or commit the workspace first and does not push the result. Existing local changes still participate in Git's normal pull and conflict behavior.

Checking Sync Status

The Git Sync settings page shows the remote URL, last successful sync, and any current error.

While a sync is running, the top breadcrumb shows Syncing. If Auto Sync is paused or Git reports an error, a warning button appears there and opens Git Sync settings.

Conflict Resolution

Choose a strategy under Settings -> Git Sync -> Sync Preferences:

• Keep Local Changes favors the workspace copy when Git resolves a conflicting edit.
• Use Remote Changes favors the incoming copy.

Octarine retries a failed pull or push before surfacing the error. Review the affected files and Git history when the automatic strategy cannot resolve a repository state.

Stopping Or Removing Git Management

These controls have different consequences:

• Turn off Manage Git in Octarine to stop Octarine from committing, pulling, or pushing. The repository and its history stay intact.
• Use Remove GitSync Integration in the danger zone to delete the workspace's local .git metadata and reset Git Sync settings. The Markdown workspace remains, but the local repository history is removed.

Removing the integration does not delete the remote repository.

Troubleshooting

• Authentication fails — verify that the SSH URL works from the terminal and that the correct key is loaded.
• Auto Sync is paused — open Git Sync settings and read the recorded error before turning it back on.
• Expected files are missing remotely — check Git Sync -> Ignored and the workspace's .gitignore.
• The wrong version won a conflict — review the Conflict Resolution setting and the repository history.
• An existing repository is not detected — confirm it has a valid .git folder and an origin remote.

Quick Answers