---
title: Git Sync
description: Clone a Git-backed workspace, configure a personal access token, and sync safely from iPhone
---

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.

> Git Sync is periodic, not real-time collaboration. Avoid editing the same note on two devices at exactly the same time. If both versions change the same lines, Octarine will ask how to resolve the conflict.

## 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](https://github.com/settings/personal-access-tokens/new). 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](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens) 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](https://docs.gitlab.com/security/tokens/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 **More**, tap the current workspace name, then choose **Manage Workspaces**.
2. Tap **Create new 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, folder coverage, and sync controls.

### Pull Changes

Tap **Pull Changes** to fetch and apply remote changes without committing or uploading local edits. It is also available in the Command Bar.

If both the phone and remote have diverged, Octarine asks you to use **Sync Now**, which can commit the local work and integrate both sides. When a conflict happens during Pull, resolving it completes the pull but does not upload the result; run Sync Now when you are ready to push.

### 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 applies only to the current workspace. Keep Octarine open while a large clone, sync, or conflict resolution is in progress.

## Folder Sync

Octarine respects the repository's `.gitignore`. Under **Settings → Git Sync → Folder Sync**, choose whether these workspace folders should sync:

- **Templates** (`/.templates`)
- **Files** (`/.files`)
- **Attachments** (`/.attachments`)

Choosing **Sync** removes Octarine's ignore rule for that folder; choosing **Don't sync** adds it. Markdown notes, Daily notes, and Inbox files remain part of the repository unless another `.gitignore` rule excludes them.

Files already tracked by Git may remain tracked after a new ignore rule is added. Other custom `.gitignore` entries are preserved.

## 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 |
| --- | --- |
| **Use Local Changes** | Uses the iPhone version of every conflicting file. During Sync Now, the resolved result is pushed. |
| **Use Remote Changes** | 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. |

**Use Local Changes** and **Use Remote Changes** require confirmation because one side can be discarded. **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

### Can I use Git Sync with an iCloud or Dropbox workspace?

No. Git Sync is available only for workspaces stored locally on the iPhone.

### Which GitHub token permission does Octarine need?

Use a fine-grained token limited to the notes repository with **Contents: Read and write**.

### What does Octarine do when mobile and remote notes conflict?

It pauses the sync and lets you use local changes, use remote changes, or keep both for manual cleanup.