Phone and sync

Org files are plain text, so the usual way to have them on a phone is to keep one directory of notes in sync between the computer and the phone and to open the same files in Neovim and in an Org app there. org.nvim needs no account and runs no sync itself: anything that copies files will do. This chapter covers the apps, the ways to sync, conflicts, and what Neovim does when a synced file changes under an open buffer (org-reload).

Apps

• Orgzly Revived (Android) reads and writes Org files. Its notebooks live in "repositories": a directory on the phone (which a file sync tool such as Syncthing keeps in step with the computer), WebDAV, Dropbox, or git. Each notebook is one .org file of the directory.
• beorg (iOS) edits Org files kept in iCloud Drive, Dropbox or on a WebDAV server; point it at the folder your computer syncs too.
• Orgro (iOS, Android) opens Org files from the phone's storage or a cloud provider's app, mainly to read them, with a few small edits.
• MobileOrg-style apps (the original MobileOrg for iOS and Android) don't edit your files directly: they sync a staging directory with the Org Mobile protocol, which org.nvim speaks. :Org mobile_push copies the files and agenda views there, :Org mobile_pull takes back the entries captured and the edits made on the phone (org-mobile). Use this only with such an app; the others need no push or pull.

Whatever the app, set it up with the same TODO keywords as todo_keywords (or the #+TODO: lines of your files), so that a state set on the phone means the same on the computer.

Ways to sync

• Syncthing (or another file sync tool) between the computer and the phone: changes reach the other side within seconds when both are online, with no server in between. On Android, give Orgzly Revived a directory repository inside the synced folder.
• A cloud folder (iCloud Drive, Dropbox, a WebDAV server such as Nextcloud): the computer's client keeps a local copy that Neovim edits as usual; the phone app syncs with the same folder.
• git: commit and pull on both sides (on the phone with Orgzly Revived's git repositories, or a git client app). The merge extension merges Org files entry by entry, so edits to different entries of the same file don't conflict (org-extensions-merge).

Set agenda_files and org_directory to the synced directory. Capture into a file the phone also opens (default_notes_file or a template's target) and what you capture on the computer shows up on the phone at the next sync.

Conflicts

When the same file changes on both sides before they sync, a file sync tool keeps both versions: Syncthing writes the other one next to the file as notes.sync-conflict-<date>-<time>-<device>.org, Dropbox as notes (<name>'s conflicted copy <date>).org. Both end in .org, so a directory or *.org glob in agenda_files picks the copy up and its entries show twice in the agenda: a sign to merge the two (:diffsplit helps) and delete the copy. git reports a conflict on pull instead, with the merge extension only where the same entry changed on both sides.

To have fewer conflicts: save before you put the computer away (the phone only sees what is on disk), let a sync finish before editing on the other side, and keep a file you edit often in both places, like an inbox, short (refile from it, org-refile).

Changed on disk (reload_on_change)

When another program changes the file of an open org buffer (a sync tool, a git pull, another editor), the buffer follows, as long as you haven't changed it:

• An unmodified buffer is reloaded at once, without a prompt. The cursor, the view and the closed folds stay where they were (a fold moves with its headline when lines are added above it), and u brings back the text from before the reload.
• A modified buffer is never touched: a warning says that the file changed and that your changes are kept. :edit! loads the file (dropping your changes); :w asks before it writes over the other program's version. Merge by hand when you want both: :w the buffer to another name, :edit!, then :diffsplit the two.
• Saving the buffer yourself (:w, or org's own saves after refile, archive, capture, agenda edits) never causes a reload.

The directory of each org buffer's file is watched (libuv file system events, on Linux, macOS and Windows), which also sees tools that save by writing a temporary file and renaming it over the original, as Syncthing and many editors do. Events are debounced (200 ms), and a buffer in Insert mode is reloaded once you leave it. At most 64 directories are watched; past that, and for every other buffer, Neovim's own 'autoread' still reloads unmodified files when Neovim gets focus or on :checktime.

Neovim 0.13 and later watch the files of 'autoread' buffers themselves. There Neovim reloads an unmodified buffer too (org still puts the folds back), and for a modified one shows its own W12 prompt (W12) instead of org's warning; answering "OK" there keeps your changes, and a later :w then writes over the file without asking.

Turn it off with reload_on_change = false; the file is then only checked by 'autoread' as above. Emacs has the same with global-auto-revert-mode, off by default there; it is on here because a buffer with changes is never reloaded and a reload can be undone.