Sync, files, and backup

Sync is never required. Everything works with Wi-Fi off. When you want history, backup, or a second machine, keep ~/devnote as plain Markdown and share it through a private git repository.

Setup in 3 steps

Authentication

devnote shells out to the git already installed on your machine. It does not store SSH keys, passwords, or tokens itself; it uses your existing SSH agent and git credential helper.

SSH

ssh -T git@github.com
# success looks like: Hi you! You've successfully authenticated…

Use SSH when possible. Keep the private key in ~/.ssh, protect it with a passphrase, and back up ~/.ssh separately from notes.

HTTPS

Use HTTPS with a credential helper so git can remember the login without devnote ever seeing it:

# macOS
git config --global credential.helper osxkeychain

# Windows
git config --global credential.helper manager

# Linux (example; needs libsecret)
git config --global credential.helper libsecret

How Sync now works

1. Export: writes changed, moved, renamed, trashed, and permanently deleted notes to ~/devnote.
2. Commit: stages everything with git add -A and commits only when something changed. The message looks like devnote: sync 2026-09-14T18:30:00.000Z (laptop).
3. Pull: runs git pull --no-rebase --no-edit when an upstream branch exists. First-time repositories report no upstream and continue.
4. Resolve or push: on conflict, devnote applies the per-file rule below and finishes the merge; otherwise it pushes, using push -u origin HEAD the first time.
5. Import: reads ~/devnote back into the app, including remote changes and preserved conflict notes.

Files on disk

Each note is one Markdown file:

~/devnote/<notebook-path>/<slug>-<id8>.md
~/devnote/.attachments/<note>-<nonce>-<name>.png

Note files carry YAML frontmatter with id, title, notebook, tags, status, pinned, trashed, createdAt, and updatedAt. Unknown notebooks import under Unsorted. Files without an id are adopted and written back with one. When the same note exists in both places, newer updatedAt wins; imports never delete notes.

Automatic disk imports

The desktop app watches ~/devnote recursively. After about 750 milliseconds without filesystem activity, plus a short app-side debounce, devnote imports changed Markdown files. A notice appears only when notes were created or updated, for example:

Mirror changed on disk: 1 new, 2 updated

The watcher skips imports while a sync is running and while a merge conflict is waiting for review. It never commits, pulls remote history, or pushes.

Attachments

Paste or drop an image into the editor on the desktop app. devnote inserts an Uploading… placeholder at the cursor, saves the file, then replaces it with a stable reference such as:

![diagram.png](.attachments/a1b2c3d4-m3xk2q-diagram.png)

• Images only: png, jpg, jpeg, gif, webp, avif, and svg.
• Size cap: 10 MiB per image.
• Filenames: note prefix, upload nonce, and original-name slug, so repeat pastes do not collide and renames do not orphan ownership.
• Preview: desktop resolves attachment bytes to a local preview image. Browsers cannot read these bytes and keep the alt text instead.
• Sync: attachments travel with normal git sync.

Conflicts

The losing version is preserved next to the winner with a fresh note id, for example:

~/devnote/engineering/sync-engine-a1b2c3d4.md
~/devnote/engineering/sync-engine-a1b2c3d4.conflict-laptop.md

The preserved note is titled Sync engine design (conflict laptop) and appears in the app for review. The red banner offers Review loser and Resolve & sync. Device names come from DEVNOTE_DEVICE, then HOSTNAME, then the machine hostname; set DEVNOTE_DEVICE for readable conflict suffixes.

Recovery

1. Open the preserved (conflict …) note and copy anything still needed into the winner.
2. Trash the preserved note only when you are sure nothing remains.
3. Click Resolve & sync to export, commit, and push the cleanup.

If a sync error leaves git mid-merge, do not hand-edit conflict markers. Run Sync now again first. As a last resort in Terminal:

cd ~/devnote
git status
git merge --abort

Status

Backup & restore

Preferences → Sync → Export backup (.zip) creates ~/devnote-backup-YYYY-MM-DD.zip from visible mirror files. Restore from backup is desktop-only: pick a zip, confirm the destructive overwrite, and devnote writes it over ~/devnote, then imports the result. Notes already open stay on screen until the next export.

iOS

There is no mobile app yet. The supported path is manual: clone the private repository in Working Copy, edit Markdown files, commit, and push. On desktop, click Sync now to pull those changes. Expect manual commits, no background sync, and possible clock skew in updatedAt comparisons. Passphrase-based git encryption remains a later roadmap item, not a built-in feature.

Errors