Emacs CalDav

Using Emacs to manage your Calendar/Diary

This post summarizes my attempts to manage my CalDav based calendars in Emacs.

Managing your Calendar/Diary in Emacs

Emacs has three main packages for managing a diary:

  • Diary Mode ships with Emacs and allows one to manage an agenda stored as a plain text file on the computer. It has many interesting features and I used it in the past, but it lacks any of the sharing and syncing functions we are used to.
  • OrgMode ships with M-x org-agenda, a command that collects time-stamped information from your OrgMode files and present them in an agenda view. By default OrgMode ships with function to sync files among different devices, but it does not provide any support for external protocols, such as CalDav (extensions exist, though).
  • Calfw is a calendar viewing framework with extensions to sync with CalDav-based calendars.

Scenario and Goals

Starting point: you are managing your appointments with Thunderbird Lightning (or another CalDav capable app) and store them on various cloud services, such as Google Calendar, Nextcloud, and iCloud.

Primary goal: you want at least to be able to use Emacs to view your CalDav calendars (this is relatively easy).

Secondary goal: you want to be able to modify your events directly from Emacs and sync them on the server (more difficult).

Viewing your CalDav Calendars in Emacs

Solution 1. Calfw

Calfw is a framework which presents a calendar in a way similar any modern calendaring application. There are of course some limitations in the experience and interaction, mainly related to the Calendar views being rendered in pure text.

The package comes with extensions meant to integrate with different backends, including iCal. This makes it possible to download a copy of your CalDav calendars locally and then display it using Emacs.

To use it, install the required packages:

M-x package-install calfw 
M-x package-install calfw-ical

and then add to your .emacs:

(require 'calfw)
(require 'calfw-ical)
(cfw:open-ical-calendar "http://SERVER/.../basic.ics")

replacing the URL with the URL of your iCal calendar. (See … for determing the URL of your iCal calendar.)

You can now display your calendar with:

M-x cfw:open-calendar-buffer

The Calfw repository is very well documented and provides detailed instructions on how to configure the package to display different calendars.

In synthesis, it is a very nice solution, but it does not work for me, since I prefer to use OrgMode and Diary to display my agenda in Emacs. Another limitation is that the week and month view might be cumbersome to use, if your calendars have many events, since there is only so much you can do with a textual table. In any other respect, it is impressive.

Solution 2. Org Caldav

org-caldav provides two-way synchronization with CalDav servers.

org-caldav downloads calendars as OrgMode documents, creating one header per event.

The package uses an ID property to mantain the correspondence between the events in the OrgMode files and those in the CalDav events. This allows to synchronize events between Emacs and a CalDav server.

For each CalDav calendar, org-caldav allows specify two OrgMode files: one for receiving the events downloaded from the server and the other for uploading events to the server or keeping the events your write directly in OrgMode. This is a kind of a safety net, so that org-caldav does not mess up with the OrgMode files you do not want to be touched by the package.

The package is available on Melpa:

M-x package-install org-caldav

Note: The installation on my machine reported an error, but the package gets installed. I am running Emacs 25.3.1 on a ArchLinux box.

To use the package, you need to specify what files get synced. This is accomplished by setting the org-caldav-calendars variable. Quoting from the documentation, you might add something like the following to your .emacs

(setq org-caldav-calendars
      '((:calendar-id "work@whatever" :files ("~/org/work.org")
         :inbox "~/org/from_work.org")
         ...
       )
)

which tells org-caldav to store events from work@whatever to ~/org/from_work.org and push events in ~/org/work.org to the server.

You start the synchronization with:

M-x org-caldav-sync

Notice that synchronization is bi-directional and changes made locally (in all files, including those used to receive events) are pushed to the server.

Notice that only basic information is synced (title, description, and date-time); other information is simply discarded (e.g., no location, no reminders).

To add an event, simply add a new time-stamped entry to your org file and sync again. For instance:

* Do something 
  <2015-06-28 Sun 18:00-20:00>

After a successful sync, org-caldav will set the ID of the event you just uploaded:

* Do something 
  :PROPERTIES:
  :ID: 905F350D-F437-4AEC-B73C-52A2B72ECBCD
  :END:
  <2015-06-29 Mon 19:00-19:25>

One important aspect to remark is that deletions are also synced. If you delete files or events, these changes will be uploaded next time you sync. If the events you delete contain invitations, emails will be sent to the attendees, even for events in the past. Be careful about this point if you want to this package a try (I did it and ended up spamming some of my collaborators, with cancellations of old events.)

One variable worth mentioning is:

org-caldav-delete-calendar-entries

that allows you to control whether events on the server are really deleted.

If your sync state somehow gets broken, you can make a clean slate by doing:

C-u M-x org-caldav-delete-everything

The package is very well documented and you can consult it for the finer grained details.

As a final remark I need to mention that in an old configuration of mine, the package did not work as-is, because of a problem in the signature of an org-mode function. To make it work I had to change the function org-caldav-generate-ics. The problem was due to a call to org-icalendar--combine-files. The fix is relatively simple. Look for the following piece of code (in org-caldav-sync):

;; New exporter (Org 8) Signature changed in version 8.2.8 (if (version<
;; org-version "8.2.8") (apply 'org-icalendar--combine-files nil orgfiles)
(apply 'org-icalendar--combine-files orgfiles)

and replace it with:

(apply 'org-icalendar--combine-files nil orgfiles)

See Adapt to signature change of org-icalendar–combine-files for some notes on the matter.

Solution 3. iCal to Diary

Another solution worth mentioning is using an Emacs Lisp function to import your CalDav files to Emacs diary files.

These files can be viewed using the diary package or with the agenda provided by org-mode.

Add the following code to your .emacs file:

(setq diary-location "a directory where you store your diary files")

; calendars you want to download
; each item links to a remote iCal calendar
(setq calendars
      '(("calendar1" . "http://.../home.ics")
        ("calendar2" . "http://.../work.ics")
        ...
        ))

(defun getcal (url file)
  "Download ics file and add it to file"
  (let ((tmpfile (url-file-local-copy url)))
    (icalendar-import-file tmpfile file)
    (kill-buffer (car (last (split-string tmpfile "/"))))))

(defun getcals ()
  "Load a set of ics calendars into emacs diary files"
  (interactive)
  (mapcar #'(lambda (x)
              (let ((file (concat diary-location (car x)))
                    (url (cdr x)))
                (message (concat "Loading " url " into " file))
                (find-file file)
                ;; (flush-lines "^[& ]") ;; if you import ical as non marking
                (erase-buffer) ;; to avoid duplicating events
                (getcal url file)
                ))
          calendars))

When you invoke the function with M-x getcals it will start downloading the iCal files specified in the variable calendars and generate one diary file per calendar. Notice that the diary files must exist in the directory specified by diary-location before calling the function.

The function erases the files and retrieves all the events every time. It is an effective strategy, since iCals don’t grow much (unless you attach documents to events). As a consequence of the previous point, each iCal must be connected to a different diary file.

To view the files in the diary, your diary file should include all files you download:

#include "calendar1"
#include "calendar2"
...

To view the Emacs diary file in your OrgMode agenda, add their paths to the org-agenda-files.

What is the iCal/CalDav URL of my calendar?

If you do not know what is the iCal or CalDav URL of your calendar, you can read the post I wrote on the matter: Determining the URL of CalDAV calendars