Synchronizing Org mode notes with a mobile device

Org mode offers an easy and convenient way to keep notes and TODO lists in Emacs. A number of apps for mobile devices allows keeping such lists on the go, but keeping them synchronized with your computer can be tedious both to setup and to run. I here present a different strategy, where synchronization is driven from the Linux computer instead of from the mobile device.

Isso logo

Emacs org-mode has a builtin method to synchronize with some of these apps. This method has a number of disadvantages however. Synchronization is not fully automatic, requiring you to press a sync button in the mobile app, open the file in Emacs, run a few commands there, and go back to your mobile phone and press that sync button again. The merge routine used in Org mode is not very powerful, so you can get merge conflicts in the simplest of cases, and the interface for dealing with those conflicts is a bit messy. I used this solution for several years, but found myself synchronizing only about once per month or so, since the process is so tedious. This method also doesn't work with Orgzly, which now seems like the only good and actively maintained app for Android.

Personally, I also want to use Git to have my notes version controlled, so I thought, "why not handle merge conflicts with the full power of Git instead"? Just transfer the Org file to the computer, commit it to a branch dedicated to tracking the status of the mobile, merge it to the master branch, and transfer it back to the mobile. Of course, merge conflicts still need to be dealt with manually, but conflicts should now be much more rare when Git is doing the merging.

The remaining piece of the puzzle is how to transfer the files from and to the mobile. By using an FTP or SSH server on the mobile phone which is configured to be always running when connected to your home Wi-Fi, everything can be driven from the computer with a simple shell script, which can then be run as a cron job. This means that synchronization can be fully automized to run nightly, and if your system is set up properly you will get an e-mail from the cron job whenever there are merge conflicts.

Setup instructions

In order to present a full solution I include the Android apps that I use myself, but you should be able to use another mobile OS, file server app, and/or org mode app.

  1. Install and configure FTP Server for Android (it's open source and also available on F-Droid and GitHub).
    • Choose a username and password.
    • Press Autoconnect settings... and select your home Wi-Fi, so that the FTP Server is always available when you're at home.
  2. Get my Mobile git-sync script by cloning the repo or just downloading the script itself, and follow the setup instructions.
  3. Install and configure Orgzly on the mobile device.
    • Setup a local repository and point it to the .org files that should now be on your device since you ran mobile-git-sync -u in step 1.
    • Enable Auto-sync. As of this writing it's marked as an experimental feature, but works well for me even with a quite large (3 MB) .org file.
  4. After testing the script manually, you could setup a cron job, for example by invoking crontab -e and adding something like:
    MAILTO =
    15 04 * * *      $HOME/path/to/mobile-git-sync

    This will run the script at 4:15 every night. To receive emails on merge conflicts you need to have a properly setup MTA on your system (instructions for Postfix and Exim). Take care not to inadvertently enable relaying though, since it could turn your system into a spamming gateway.