Git Sync

Git Sync keeps an on-device workspace in a remote Git repository. Octarine can clone the repository onto your iPhone, commit changes made on the phone, pull changes made elsewhere, rebase the phone's commits on top of them, and push the result.

Git Sync is available only for workspaces stored On this iPhone. iCloud and Dropbox workspaces use their own storage sync and do not show the Git Sync settings page.

Before You Begin

You need:

• A remote Git repository containing at least one supported Octarine file, such as a Markdown note. The iOS clone flow cannot import an empty repository.
• The repository's HTTPS URL, for example https://github.com/you/notes.git.
• For a private repository, your Git host username and a personal access token (PAT) with permission to read and write that repository.

Public repositories can be cloned without credentials, but pushing still requires write access.

Create a GitHub Personal Access Token

GitHub passwords cannot be used for Git operations over HTTPS. Use a fine-grained personal access token instead.

1. Open GitHub's fine-grained token settings. If needed, sign in to GitHub first.
2. Enter a descriptive Token name, such as Octarine iPhone.
3. Choose an Expiration. When the token expires, Git Sync will stop authenticating until you replace it in Octarine.
4. Under Resource owner, choose the user or organization that owns the notes repository.
5. Under Repository access, choose Only select repositories, then select only your notes repository.
6. Under Repository permissions, set Contents to Read and write. GitHub automatically includes the metadata access it requires.
7. Leave unrelated permissions set to No access, then tap Generate token.
8. Copy the token immediately and store it somewhere safe. GitHub will not show the full value again.

GitHub organization repositories may require an administrator to approve the token. A token waiting for approval can read public resources only, so cloning or pushing a private organization repository may fail until it is approved. See GitHub's PAT documentation for organization policies, expiry, revocation, and classic-token instructions.

If you use a classic GitHub token instead, it needs the repo scope for a private repository. Fine-grained tokens are safer because they can be limited to one repository.

GitLab Tokens

For GitLab, create a personal, project, or group access token with write_repository, which includes Git-over-HTTPS read and write access. See GitLab's access-token scopes. Enter your GitLab username and use the token in Octarine's Token field.

Clone the Repository as a Workspace

Git-backed workspaces are created by cloning the remote repository:

1. Open the workspace switcher from the workspace pill on Home, or go to Settings and return to the workspace chooser.
2. Tap Create Workspace.
3. Select Clone from Git.
4. Paste the repository's HTTPS URL into Repository URL.
5. For a private repository, enter your Git host Username and the PAT in Token for private repos. Leave both fields empty for a public repository that does not require authentication.
6. Optionally choose the workspace color. The workspace name is taken from the repository name.
7. Tap Clone repository and keep Octarine open while it downloads, checks out, and imports the files.

The clone is stored locally at On My iPhone → Octarine → repository-name. Git workspaces cannot be cloned into iCloud or Dropbox.

Octarine imports supported notes, folders, daily and weekly notes, templates, Inbox captures, attachments, and files from the clone. It then opens the workspace, enables Auto Sync, and sets the initial interval to 10 minutes.

If a folder with the repository name already exists in Octarine, choose a different repository name or remove the existing folder before trying again.

Credentials and Security

The token is saved for this workspace in Octarine's encrypted on-device credential vault, protected by the Apple Keychain. It is not written into the repository URL or into a note.

To change it later, open Settings → Git Sync:

• Replace credentials lets you enter a new username and token, which is useful after rotation or expiry.
• Remove deletes the saved credentials for this workspace. Public fetches may continue to work, but private fetches and authenticated pushes will fail until credentials are added again.

Treat a PAT like a password. Do not paste it into a note, commit it to the repository, or send it in a support request. If it is exposed, revoke it at your Git host and create a replacement.

Syncing

Open Settings → Git Sync to see the remote repository, last successful sync time, credentials, and sync controls.

Sync Now

Tap Sync Now on the Git Sync page. You can also pull down to open the Command Bar and run Sync Now under Git Sync.

For each sync, Octarine:

1. Creates a local commit for all changed, non-ignored files with the message Updated from Octarine iOS.
2. Fetches the current branch from origin.
3. Fast-forwards when only the remote has changed, or rebases the phone's commits on top of the remote branch when both sides have changed.
4. Pushes the current branch back to origin when the phone is ahead.

If the phone is offline, Octarine can still create the local commit. The pull and push wait until a later sync after connectivity returns.

Auto Sync

Turn on Auto Sync, then choose an interval of 5, 10, 15, 30, or 60 minutes. Auto Sync also checks when Octarine returns to the foreground and when the phone comes back online.

Auto Sync applies only to the current workspace. Keep Octarine open while a large clone, sync, or conflict resolution is in progress.

What Gets Committed

Octarine respects the repository's .gitignore. If the repository does not already have one, the first sync creates a default file that ignores:

/.attachments
/DS_Store
/node_modules
/.templates
/.files

This means Markdown notes, folders, Daily notes, and .octarine/inbox/ are included by default, while potentially large attachments, general files, and templates are not. Files already tracked by the repository remain tracked even if they match a later ignore rule. Edit .gitignore on another Git client if you want different coverage, commit that change, then sync it back to iOS. Existing .gitignore rules are left unchanged.

Resolving Conflicts

Octarine first tries to integrate mobile and remote work automatically. If the same file cannot be rebased cleanly, Settings → Git Sync shows the conflicting paths and three choices:

Choice	Result
Keep this device	Uses the iPhone version of every conflicting file, then pushes it. Remote conflicting versions are replaced.
Keep remote	Uses the remote version of every conflicting file. Conflicting changes from the iPhone are discarded.
Keep both	For text files, places the remote text first and the mobile text after an Octarine Git Sync: mobile version comment. For binary files, keeps the remote file at its original name and saves the phone's copy with a .mobile-conflict suffix.

Keep this device and Keep remote require confirmation because they can discard changes. Keep both preserves the material for manual cleanup, but the combined text may contain duplicated paragraphs or invalid frontmatter. Open every affected file after the sync, reconcile it, and sync again.

Conflict choices apply to all paths listed for that failed sync, not one file at a time.

Troubleshooting

Authentication failed

• Confirm that the repository URL begins with https:// and points to the correct repository.
• Use your Git host username, not your email address, unless your host explicitly requires otherwise.
• Check that the token has not expired or been revoked.
• For GitHub, confirm that the token's resource owner and selected repository are correct, Contents is Read and write, and any organization approval has completed.
• In Settings → Git Sync, choose Replace credentials, save the new token, and try Sync Now again.

Clone finishes downloading but nothing is imported

The repository must contain a supported note, folder, attachment, or file. Add and push at least one Markdown note from another Git client, then clone again.

Push is rejected

Confirm that the account behind the token has write access and that branch protection allows direct pushes to the checked-out branch. Octarine pushes the repository's current branch directly; it does not create pull requests.

The remote changed while the phone had edits

Run Sync Now. Octarine rebases the phone's commits on top of the fetched branch. If the changes overlap, use the conflict controls described above.

I no longer want Git Sync

Turn off Auto Sync and remove the saved credentials. Forget Git Sync Settings clears Octarine's saved sync preferences, but it does not delete the workspace or its .git history.

Quick Answers