π

UOMF: Recurring Events with Org Mode

Show Sidebar

Silent update 2019-09-25: added to blog series "Using Org Mode Features"

Please do read my "Using Org Mode Features" (UOMF) series page for explanations on articles of this series.

Org-mode has time-stamps which can be written manually or added via commands like C-c . (org-time-stamp()). Note that I am using inactive time-stamps (brackets instead of angle brackets) in this blog entry to prevent my agenda from showing all those example time-stamps:

 [2017-01-15 Sun] day
 [2017-01-15 Sun 12:19] time
 [2017-01-15 Sun 12:19-15:00] time period
 [2017-01-15 Sun]-[2017-01-17 Tue] date period
 [2017-01-15 Sun]--[2017-01-17 Tue] date period (alternative style)	  

When a task or an event is repeated again and again, Org is able to express it for most cases as well:

 [2017-01-15 Sun +1w] every sunday
 [2017-01-15 Sun +3d] every three days starting with this sunday
 [2017-01-15 Sun .+1w] every week after the day this task was finished
 [2017-01-15 Sun ++1w] like .+1 but it stays on the next Sunday after finishing	  

Complex recurring items can be defined using special sexp diary entries:

 * 22:00-23:00 The nerd meeting on every 2nd Thursday of the month
 [%%(diary-float t 4 2)]	  

However, for many standard recurring events (like +1w) and for everything advanced where I'd need sexp expressions, I do prefer a different approach: M-x org-clone-subtree-with-time-shift

And this is why.

The Problem with Repeater Intervals

Let's assume, we are joining a volleyball team which has a training on Monday 7pm to 8:30pm. This can be easily defined like:

 * [2017-01-16 Mon 19:00-20:30 +1w] Volleyball training	  

This creates a recurring event on the agenda.

There are several issues with this approach:

What about cancellations or school holidays, where there is no sports hall available?

I'd have the recurring event on my agenda without the possibility to define exceptions.

Further more, when I want to add notes to specific trainings, I'd end up with a very long body for this single training heading.

Org-Knowledge to the Rescue

To prevent all those issues mentioned above, I use M-x org-clone-subtree-with-time-shift (or C-c C-x c if you can remember it).

You simply create one instance of your event without any repeater interval and invoke M-x org-clone-subtree-with-time-shift. Then, Org asks you how many copies it should create and an optional time-shift between those instances.

With our volleyball example, this would look like that:

 * [2017-01-16 Mon 19:00-20:30] Volleyball training	  

Then invoke M-x org-clone-subtree-with-time-shift, ask for twenty copies (or how many weeks in advance you want to define trainings), and a time-shift of 1w.

Then you end up with following headings:

 * [2017-01-16 Mon 19:00-20:30] Volleyball training
 * [2017-01-23 Mon 19:00-20:30] Volleyball training
 * [2017-01-30 Mon 19:00-20:30] Volleyball training
 * [2017-02-06 Mon 19:00-20:30] Volleyball training
 [...]	  

Now you have in total twenty-one instances of your volleyball training event. You are now free to delete single occurrences (canceled trainings), delete a series of trainings (school holidays with no hall), move single occurrences to different days (exceptions), and you are able to add notes to single trainings more easily.

I am using this method instead of sexp expressions for advanced recurrence definitions like «every second Tuesday of the month». I clone an event with a almost fitting period like +4w. Then I manually change the instances to fix them. I move to the months where +4w did not result in the second Tuesday and use Shift left and right to modify the time-stamp.

It is highly recommended to create a simple recurring todo scheduled after the last clone which reminds you of creating the clones for the next series of events.

A Workaround That Turned Out to Be Superior

When I started with Org-mode, I was using a Palm Pilot with a very capable DateBk3 software. Since DateBk3 had easy-to-use and advanced features for defining exceptions and irregular periods, I was disappointed by Org-mode at first.

However, when I started to use org-clone-subtree-with-time-shift with its instance copies, I began to favor this method because of the advantages I mentioned above.


Related articles that link to this one:

Comment via email (persistent) or via Disqus (ephemeral) comments below: