Updated 23 August 2026

English 简体中文 繁體中文

Syncing a vault

A vault is a folder of Markdown files. Nothing about it is proprietary, so there is more than one sensible way to get it onto a second device. Inkstone offers two, and they are good at different things.

They are not exclusive. A vault can sit in iCloud Drive and push to GitHub; iCloud moves it between your own devices quickly, GitHub keeps the history and the off-Apple copy.

iCloud Drive

There is no switch to turn on, and none to turn off. Whether iCloud carries a vault depends on where the folder is: put it in iCloud Drive and the system syncs it. No app can stop that, and Inkstone does not pretend to — to stop it, keep the folder somewhere else.

The one setting here is Keep files downloaded, on by default. iCloud saves disk space by evicting the contents of files you have not opened recently, leaving a placeholder behind. To Inkstone a placeholder is an empty note, so a vault that has been sitting idle can look like a vault that has lost its notes. Turn it off only on a device genuinely short of space.

GitHub

You need a repository — private is fine, and normal — and a fine-grained personal access token with Contents: read and write for that repository. The token is stored in your Keychain, never in the vault and never in the settings file.

First device

1. Open the vault you want to sync.
2. Settings › Sync, turn on Sync this vault with GitHub.
3. Paste the token, choose the repository and branch.
4. Sync now.

Second device

Start with an empty folder. This matters more than anything else on this page.

1. Make a new, empty folder and open it as a vault.
2. Enter the same repository and branch.
3. Sync. You will be asked which side wins — choose Keep GitHub's.

Pointing a folder that already has notes in it at a repository that has different notes in it is asking two unrelated sets of files to become one. The app cannot know which is which, so it keeps both, and you get a conflict copy of every file that differs.

One repository, one vault, per device

Two folders on the same device cannot both hold the same repository. Inkstone refuses it, and neither of them syncs until one gives it up.

This is not a limit, it is the arrangement that has no correct behaviour: every sync makes the repository look like whichever folder ran last, so the two overwrite each other in turn. Nothing about it is recoverable by being cleverer — there is no way to tell which of two working copies is meant to be the repository.

The pane names the vault that already has it and offers to move it, rather than simply refusing: a binding outlives the folder it was made for, and a refusal with no way through would leave you unable to use that repository anywhere.

Two devices sharing one repository is the whole point, and is unaffected.

When a conflict happens

Exactly one situation produces one:

That is the whole rule. Each sync compares three things for every file: what is here, what is on GitHub, and what the last completed sync recorded. If only one side moved, that side wins and nothing is ambiguous. If both moved, there is no answer the app can pick for you.

Which means:

• Editing on one device, letting it sync, then editing on the other — never conflicts, however long you leave it.
• Editing different notes on two devices — never conflicts, however stale either side is.
• Editing the same note on two devices before a sync — conflicts, and should.

A conflict never overwrites anything. GitHub's copy is written beside yours as Note (conflict 2026-08-23 1420).md and both survive. Open them, keep what you want, delete the other. The copy is made once, not once per sync.

The first sync is the exception

Before the first sync there is no record of the two sides ever agreeing, so every file that exists on both and differs looks like “both changed”. Rather than making a conflict copy of each, the app asks you once — keep this device's, keep GitHub's, or keep both — and remembers the answer.

Having fewer of them

• Sync before you switch devices. On iOS the sync keeps running after you leave the app, and the system shows its progress until it finishes.
• Let the phone finish before you edit on it. The Sync pane shows a progress bar and a file count while it works.

How often it actually runs

The interval you choose is a floor, not a promise.

On macOS the app is running, so it holds. On iOS the system decides: it budgets background time from how often you open the app, and it will not wake an app you have force-quit from the app switcher until you open it again. Expect a few background runs a day rather than one every interval. Background App Refresh must be on, and Low Power Mode suspends it entirely.

Settings › Sync shows what the system has actually been doing — when it last woke the app, and a log of each attempt.

If the vault is a git working copy

If the folder has a .git directory in it, Inkstone's GitHub sync switches itself off and says so.

This is not a limitation, it is the two mechanisms disagreeing. Git merges: three-way, with a history, and conflict markers a person resolves. Inkstone's sync works file by file and last write wins. Run both over one folder and each undoes the other's results.

The arrangement that works is one writer per mechanism:

Git on the desktop, Inkstone on the phone. The phone's changes arrive on the desktop through git pull; the desktop's reach the phone once pushed. Pull before you commit — the phone writes to the same branch.

There is a per-vault override if you want to sync a git working copy anyway. It is off unless you ask for it.

What Inkstone refuses to do

A few situations look like an instruction and are almost always an accident, so the sync stops instead of carrying them out.

• The repository has gone empty but files were recorded there before. An empty listing is far more often a wrong branch or a token that lost access than a deliberate wipe — and the response to a deleted remote file is to delete the local one.
• The branch does not exist. The message names the branches that do.
• The vault is a git working copy, as above.

An interrupted sync is safe: what it moved is kept and the next run continues from there rather than starting over.

Which files travel

Notes and canvases always sync. Attachments sync by kind — images, audio, PDFs, video, everything else — each with its own switch, plus a size limit. Settings › Sync has them.

A .gitignore in the vault root is obeyed, and travels with the vault, so a second device gets the same rules rather than uploading everything the first one deliberately left out.