Capture mode and Date Trees in org-mode

Capture mode and Date Trees

An important piece of functionality in org-mode is the ability to capture notes and ideas (using capture mode) and storing in a nominated location. Date Trees are a method of specifying a location based on the date.

What is Capture?

Capture is a facility for quickly adding to your org-files with minimal disruption to your work flow. It supercedes the remember module but is similar in operation. The basic worklow of using capture is as follows:

  1. Invoke capture. I use the F6 function key which is bound to org-capture in my .emacs file: (global-set-key (kbd "<f6>") 'org-capture)
  2. A new window is displayed with a list of templates. Each template has an associated short cut key, for example n for notes and t for a Todo-list item.
  3. Enter the short cut code, for example n for note
  4. Type the text
  5. File the note C-c C-c
  6. Continue whatever you were working on.

If you would like to go to the point where the item was filed, enter the very useful command C-u C-u F6.

Capture templates

Each template is set up in the .emacs file or by customising org-mode options. The components of a capture element are described in section of the manual but here is a summary:

  • a shortcut key (a letter)
  • a description of the template
  • a type of entry. These can be an org-mode entry (node) with a headline, an item in a list, a checkbox item (checkitem) , a line in a table (table-line) or plain text.
  • a target specifying where the captured item should be placed
  • a template - a strng of text with special escape codes for date stamps, prompt strings, etc
  • additional behaviour properties (I am still stumped on how to set up "property lists")

These are my capture templates on my office computer:

(quote (
("a" "Appointment" entry (file+headline 
"c:/charles/My Dropbox/GTD/" "Calendar") 
"* APPT %^{Description} %^g
Added: %U") 
("n" "Notes" entry (file+datetree 
"c:/charles/My Dropbox/GTD/") 
"* %^{Description} %^g %? 
Added: %U") 
("t" "Task Diary" entry (file+datetree 
"c:/charles/My Dropbox/GTD/") 
"* TODO %^{Description}  %^g
Added: %U") 
("j" "Journal" entry (file+datetree 
"c:/charles/My Dropbox/GTD/") 
"** %^{Heading}")  
("l" "Log Time" entry (file+datetree 
"c:/charles/My Dropbox/GTD/" ) 
"** %U - %^{Activity}  :TIME:")

Note how the templates are spread across multiple lines. If you want some text to start on a new line then format the template accordingly. For example the "Added:" text starts on a new line.

Here is screen capture of Emacs after capture mode was started with F6. Compare the descriptions and short cut keys to what is displayed.


Some notes about this configuration:

  • I save my files in a folder which is synchronised between my office and home computers using the web-based DropBox service.
  • %^g prompts for a tag
  • I timestamp all my captured items with the line: Added: %U
  • Some of my items are filed after a specific headline in a file. Appointments are filed under a heading Calendar.
  • Other entries are filed in date trees. These are explained in the next section.

Date Tree Format

A date tree is a set of headlines used to capture information by date. There are three levels of headlines, each with a specific format:

  • Level 1 headline for the year (YYYY)
  • Level 2 headline for the month (YYYY-MM Monthname)
  • Level 3 headline for the day (YYYY-MM-DD Dayname)

Here is a screen capture from one of my files showing a date tree.


Capturing to a date tree

Capture uses template definitions (stored in your .emacs startup file) to define where information should be stored and in which file. One of the target types is a date tree: (file+datetree "path/to/file").

When a new headline is created in a date-tree, Capture searches from the beginning of the target file looking for a match on the year. If it is not found, then a level one headline is created. The process is repeated for the month then the day. Missing months and missing day headlines are not created to fill in gaps.

It is possible to attend text to the headlines and not interfere with Capture. This allowed me to manually enter the week number (read from the agenda view) to help me indentify the beginning of the week. You may want to add tags to these headlines.

Practical uses of Capture and Date Trees

I am used to writing notes in a hardcover notebook. This is my journal where I rule a line at the beginning of each day, write the date and day then add notes during the day. Date trees and capture allow me to replicate this functionality.

I am also used to using a diary for identifying appointments and deadlines. The agenda view gives me this functionality with the need to move brances (headings) in my org-mode files.

Date trees give the functionality of writing entries into a "diary" on a dated page. I use a file named to capture my notes and "To Do" list items as branches on the tree.

The Notes template prompts for a headline text then positions the cursor under the headline to type or paste text.

The Task templates prompts for a headline text as well as a category tag. The TODO keyword is included in part of the template.

In both templates I add the date and time created as this provides useful tracking information, especially when items are refiled.

I could have captured notes in one file and To Do items in another file, but I wanted notes and tasks to coexist "on the same page". Sometimes I will convert a note into a TODO item and it is easier to do this when the item is stored in the same file.

The Journal template is used to record information for long term storage such as diary entries, details of books I have read and things I have done. Once an item is in the Journal file I don't move it. I only use the Journal file on my home computer.

The Log Time entry is something I started this week to track what I do all day at work. Every time I start a new task or have a break I log a a brief description. Here is a view of my day so far:


The Receipts is used for recording payment details resulting from Internet banking and online commerce sites. I found it is more suitable to keep financial information separate from other journal entries.

This template is only set up on my home computer as I only work on personal finance at home.

My productivity system

Here is a screen capture showing part of the Task Diary


On Wednesday (2010-10-06) you can see one To Do item with context of COMPUTER and two note items. On Tuesday (2010-10-19) there are two To Do items and 3 completed (DONE) tasks.

This date-tree is the basis of my task management system.

Items are added as follows:-

  • Todo items are added with the t capture template. A tag is added to give context and a scheduled or deadline date can be added with the appropriate command (C-c s and C-c d respectively)
  • Notes are added with the n capture template.

When I need to decide what to do next, I use the following methods:

  • Agenda view - identify items marked with Scheduled or Deadline dates
  • Tag view - show tems marked with a tag (my GTD contexts, eg HOME, OFFICE, FINANCE, READING, DVD)
  • Reviewing this weeks nodes - Each day I quickly scan the items added since the beginning of the week.

Read more articles about org-mode and productivity