Syncing your Org Mobile data

January 09, 2019

Org Mobile is a protocol for a mobile Org workflow. It has some great features and a few drawbacks. In this post, I discuss an Emacs configuration that enhances my use of the protocol by tying the sync step into it.

Org Mobile works by creating an intermediate copy of your Org files in a designated directory for a mobile app to read and write to. The same package then provides commands to reingest the modified data and propagate its changes.

I believe MobileOrg is the only app to actually use the Org Mobile protocol.¹ It is a free and Open Source app. The iOS version was last updated in 2020, and there is an Android version last updated in 2018. Others, such as beorg and Orgzly, simply synchronize the Org directory itself to edit the files directly.

Staging the files that will be synchronized in an intermediate location, as Org Mobile does, has its advantages. It can make it easier to recover from an accidental edit or a sync error. The most compelling reason to use Org Mobile must be the built-in encryption, which means there's not as much of a need to trust the server in which you store your notes.²

On the other hand, the most compelling reason not to use must be that you need to remember to run the functions in Emacs to push and pull the notes, or implement your own automation to that end. No doubt some users will also find that the MobileOrg iOS app disappointing for its lack of fancy features and not using the latest UI frameworks.

With the configuration below, I've tried to mitigate some of this, according to my own priorities, by building the sync step into the Org Mobile commands, removing the need for an always-on synchronization daemon.

How it works

With the following code in your dotfile, every time you run org-mobile-push, Emacs will (1) clear the Org Mobile directory, (2) write your Org Mobile data to it, and (3) use rclone to sync the newly written files.

On the other end, every time you run org-mobile-pull, Emacs will (1) clear the Org Mobile directory, (2) fetch the data from the cloud—where it may have been updated by your mobile app, and (3) push its changes into your Org directory.

This is done by creating functions that perform those operations and adding them to hooks that run with org-mobile-pull and org-mobile-push. Find the entire code example in this Github gist.

Note: In the code examples below, it's assumed that the local Org Mobile directory is ~/mobileorg and that rclone is configured with a cloud service named Dropbox, within which the Org Mobile directory is Apps/MobileOrg. For more information on rclone configuration, visit https://rclone.org/.

Clearing the Org Mobile directory

Because org-mobile-push does not update the Org Mobile directory but rather just pushes to it, it won't remove files that have been deleted. In practice, this doesn't really matter because your mobile app should only fetch the files listed in the index.org file anyway, so this step can be considered optional.

(defun org-mobile-clean-pre-push()
  (with-temp-buffer
    (shell-command "rm ~/mobileorg/*" t)))

When running shell-command, Emacs will show a buffer with the results of your command. We don't want to see those, in this case, and they're normally going to be blank anyway. By running the command inside with-temp-buffer, that buffer won't persist.

Pushing

--exclude \.DS_Store is used to ignore macOS system files. Obviously, you may leave this out if you're on another system.

The function below will run rclone sync³ to upload the Org Mobile data.

(defun org-mobile-rclone-sync-post-push()
  (with-temp-buffer
    (shell-command "rclone sync ~/mobileorg Dropbox:Apps/MobileOrg --exclude \.DS_Store" t)))

Pulling

Since we only need to run extra actions before org-mobile-pull runs, they can all go in the same function.

(defun org-mobile-rclone-sync-pre-pull()
  (with-temp-buffer
    (shell-command "rm ~/mobileorg/*" t)
    (shell-command "rclone sync Dropbox:Apps/MobileOrg ~/mobileorg" t)))

Adding hooks

(add-hook 'org-mobile-pre-push-hook 'org-mobile-clean-pre-push)
(add-hook 'org-mobile-post-push-hook 'org-mobile-rclone-sync-post-push)
(add-hook 'org-mobile-pre-pull-hook 'org-mobile-rclone-sync-pre-pull)

Automatically syncing

With the code below, Emacs will automatically push your notes before shutting down, and pull them at startup. If you run Emacs as a daemon, this should be left out. Also, you may find that this slows down your Emacs start-up too much. Consider these to decide whether to use this snippet or not.

(add-hook 'kill-emacs-hook 'org-mobile-push)
(require 'org-mobile)
(org-mobile-pull)

We must use (require 'org-mobile) to make sure Emacs loads the org-mobile feature available. If org-mobile is not available, Emacs won't know the org-mobile-pull function. This step may not be necessary if another Org mode feature has already been called earlier in your init.el file.⁴

Further work

Although the Org Mobile protocol makes for a safe and clever way to synchronize Org notes, its only implementations for mobile platforms have been unmaintained for a long time, and risk not working well on recent mobile OS versions. Meanwhile, there are a few applications for Android and iOS that rely on other ways to synchronize Org files, but are quite well done. The best examples, I think, are beorg on iOS and Orgzly on Android. Unfortunately, none of these support Org Mobile sync.

I've seen other interesting mobile Org workflows around the web that I plan to work on in the future. In particular, the question of whether to automatically trigger sync remains open. Also, some research is needed on figuring out whether org-mobile-push pushes every file regardless whether or not it has been changed (which would mean we should never clear the Org Mobile directory), and whether rclone makes the same decision based on modified date or hash. Those answers may show us how to make syncing faster.

Please share your thoughts and ideas on this, or if you have seen any code that can fill a gap here.

Send me an email.

The words mobile and org will dance around each other nauseatingly all over this article. Org Mobile is the protocol, MobileOrg is a mobile app that happens to use it, and org-mobile is the Emacs feature, as denoted in Emacs.↩︎
Note that Org Mobile will not encrypt the file names, just their contents. It's very likely that the encryption used by Org Mobile is not up to today's standards. So, you should still make sure the netork location you use has some protection.↩︎
Usage: rclone sync [source] [destination] [options]↩︎
For example, the Spacemacs Org configuration layer makes it unnecessary to call (require 'org-mobile) because it will have loaded it before it runs your dotspacemacs/user-config.↩︎