org-mode is an Emacs package for creating outlines with enhancements to make it a powerful tool for personal productivity, planning and simple project management. org-mode is an appointment book, calendar and to-do list manager.
This tutorial focuses on the date and time stamp functionality and how this works with the agenda view.
The basics of an org-mode file are lines beginning with one or more asterisks to indicate an outline entry (or heading), with the number of asterisks indicating the outline level. Text associated with an outline entry follows the line beginning with asterisks until the next outline entry.
The simplest outline looks like this:
* Things to do at work ** Weekly management meetings *** Tuesday department meeting (10-11am) *** Friday afternoon team meeting (3-4pm) * Phone calls to make ** Susan - regarding contract
org-mode makes good use of color and font decorations to make this very simple text readable.
org-mode enhances the outline entries with the following features of user configurable tags, to-do flags and dates.
These are useful for defining places where the work can be done, contexts, type of work, people involved , or special resources. For example: HOME, OFFICE, PHONE (identifying items requiring a phone call), BOSS (tagging items to discuss with your manager) and SUSAN (tagging items delegated to SUSAN).
Tags appear at the end of an entry with surrounding colons. Tags are
assigned using the
C-c C-c command where a window is displayed showing
the tags configured in the line beginning
#+TAGS. Each tag can be
followed with a short-cut for fast selection.
Tags are used to generate lists of items containing one or more specified tags. For example, a list of phone calls that need to be made can be generated by searching for the PHONE tag. These lists by context are known as Next Actions in David Allen's Getting Things Done methodology.
An outline entry can be marked as TODO using the
C-c C-t command.
This tag appears at the beginning of an entry in a different colour.
To-do flags are used to generate a "to-do list" sparse tree using the
C-c C-v command, or in a agenda buffer described later in this tutorial.
An item can be marked with a date indicating when the activity should take place. In addition dates can be assigned to record scheduled start dates, deadlines and ranges of dates. This functionality allows org-mode to be used as a planner, appointment book and simple project management tool.
The user manual describes dates and times in section 8, titled "Timestamps". I think this name is confusing, because a timestamp is a combination of date and time recording when an event occurred. I will not use the word timestamp again in this tutorial!
Dates can appear anywhere in the headline or body of the outline entry. The following two entries are functionally equivalent:
* Win the lottery <2007-10-21 Sun> * Win the lottery again <2007-10-21 Sun>
Outline entries can be tagged with several combinations of dates, times and ranges for display in agendas, timelines, or a "sparse-tree" of items approaching a deadlines.
Now let's explore these various date and times.
A simple date is specified in a special format enclosed in angle or square brackets, for example, <2007-10-21 Sun> or [2007-10-21 Sun].
The angle bracket notation is for active dates which will appear in agendas and timelines. The square bracket notation is for inactive dates for recording when things happened, and will not appear in agendas or timelines.
C-c . command is used to prompt for an active date whereas the
C-c ! command prompts for an inactive date. The procedures for
choosing a date are the same for both types of dates.
An Emacs Calendar frame is displayed above the mini-buffer.
The response to this prompt is combined with the date currently selected in the calendar prompt. Since the calendar is displayed with today's date being active, hitting Enter will choose today's date.
The date currently displayed in the calendar prompt is referred to as the default date and can be changed with the following navigation commands:
Here are some of the many ways you can respond to the prompt and how it modifies the default date. Assume the default date is Sunday, 21st October 2007.
A relative date can be given as the first thing in the input by typing a plus (+) or minus (-) sign, a number and a letter (d, w, m, or y) indicating a change in days, weeks, months or years to today's date.
A double plus or double minus sign makes the input relative to the default date.
Here are the results of the insertion of inactive dates with various inputs:
After you have answered the prompt, a date string is inserted into the buffer.
A time can be added to a date using the methods described in the
previous section but adding the time in HH:MM format. For example,
+1 11:00 gives .
Events with a definite ending time can be recording using two times separated with a hyphen, for example.
A range of dates can be recorded using two dates separated by a
hyphen. These can be entered by entering the first date with
then immediately running the
C-c . command again.
The agenda gives an overview of date and time tagged headlines, sorted chronologically.
Let's see how the various dates and times from the buffer above are displayed in the agenda.
The headlines of the items are displayed in the appropriate day.
(1/3): James on Leave.
sample2. This can be changed by include the #+CATEGORY: tag at the beginning of the buffer to give a meaningful name.
A timeline is another view of the date and time-stamped items in the current file. The main purpose of a timeline is to give an overview over events in a project.
A timeline is generated from the
Org > Special Views Current File > Timeline menu item or issuing the
C-c a L.
Some tasks need to be repeated at regular intervals - daily, weekly, fortnightly, monthly, quarterly and annually. Items can be made to repeat in the agenda view by including a repeater directive at the end of the date. This has the format of a plus sign, a number and a letter indicating a unit of time: days (d), weeks (w), months (m) and years (y).
Therefore, the weekly meeting entries can look like:
*** Tuesday department meeting <2007-10-23 Tue 10:00-11:00 +1w> *** Friday afternoon team meeting <2007-10-26 Fri 15:00-16:00 +1w>
Viewing the agenda and scrolling forward into future weeks will show the date entries.
A time stamp can be preceded with a special keyword to facilitate planning your work.
A task, most likely flagged with TODO, is supposed to finish by a deadline date. Work on the task can begin as soon as practical, but must be finished by the deadline date.
A deadline date is entered with the
C-c C-d command. The method of
entering dates is the same as described previously, but the end result
is the additional keyword
DEADLINE: preceding the date:
The list above shows an item due today (Sunday report) and an overdue item (Weekly Report) due last Friday. Here is the agenda generated on Sunday 21st October.
An item with a deadline date is displayed in red on the deadline date with a prefix of "Deadline:".
If the deadline is within the number of days set by the
ord-deadline-warning-days variable, the information is repeated on
today's date with the number of days until the deadline, for example,
"In 5 d".
When an item is overdue, the entry is shown in red with the number of days overdue, but shown as a negative number.
If you would to have a longer or shorter warning about an upcoming deadline, include the interval preceded with a minus sign at the end of the date string. The following entry will generate an item in the agenda with the number of days until the 31st January 2008.
* Product Sofware Release Date DEADLINE: <2008-01-31 Thu -6m>
The agenda line generated today from the entry above is:
Planner: In 102 d.: Product Sofware Release Date
When a task with a deadline, such as a weekly or a monthly report, needs to be tracked, it can be set up with a TODO tag and a repeater interval. A weekly report due on midday each Monday could be set up as follows:
** Submit Weekly Report DEADLINE: <2007-10-22 Mon 12:00 +1w>
This will display each Monday on the agenda. If the entry is changed to a TODO item, work on the report can be tracked.
** TODO Submit Weekly Report DEADLINE: <2007-10-22 Mon 12:00 +1w>
When the TODO item is closed with
C-c C-t a window is opened where
you can record a note about closing the task. A date and time stamp
is recorded. Note that the date has been increased by the repeater
interval, the item is still in the TODO state, and the note is
recorded under the item.
The deadlines in the current buffer can be checked with the
command. This displays the items that are past due or will become past
org-deadline-warning-days. Just enough of the buffer is
displayed to give context to the items. This feature is not normally
used, so the keybinding may be removed at a later date.
With a numeric prefix, check deadlines that fall within that number of
days. For example,
C-30 C-c C-w will display all deadlines that fall
within 30 days. This can also be entered as
Esc 30 C-c C-w.
A scheduled date is when you plan to start working on a task. The item
will be listed in the agenda on the scheduled date. A reminder will
also be given when a scheduled date is in the past, until the item is
marked as done. A date is marked as scheduled using the
C-c C-s command.
Do not confuse a scheduled date with an event marked with a specific date. Although you use the verb schedule to say "I have scheduled the weekly meeting", this usage of scheduled has a specific meeting.
For example, I can schedule an item to pay my credit card on the 21st of the month, because I get paid on the 20th of each month. An entry could be set up as:
** Pay credit card statement SCHEDULED: <2007-10-21 Sun +1m>
This will be displayed as:
Scheduled dates and Deadlines can both be supplied for an entry. The earliest day of the month I can pay my credit card is the 21st of the month, however the payment is due by the last day of the month. Therefore I can enhance the entry with a deadline:
** TODO Pay credit card statement SCHEDULED: <2007-10-21 Sun +1m> DEADLINE: <2007-10-30 Tue +1m>
Once the item is marked DONE, both dates are advanced by the repeat interval to next month.
The agenda display above shows an event scheduled for last week and this is highlighted in red with how many days overdue.
A date can be edited in several ways. The date can be scrolled forward or backwards by positioning the cursor anyway inside the date string and entering Shift-Right Arrow to go forward a day, or Shift-Left Arrow to go back a day.
Individual components of a date (Year, month and day) can be changed by positioning the cursor on the number to be changed and clicking Shift Up Arrow or Shift Down Arrow to adjust the value. The day of the week corresponding to the date will be adjusted accordingly.
A date can be chosen with the Emacs calendar by positioning the cursor
anywhere in the date and entering the
C-c . command. The date can be
edited according to the methods described in the earlier Simple Date
C-c > command opens the Emacs calendar window displaying the
date under the cursor. For example, if the cursor is over the date
string <2007-01-01 Mon>, issuing the command will display a calendar
with January 2007 in the middle. You can navigate using the commands
described in the previous section then choose a date with a
mouse-click or pressing Enter.
The date you have chosen is now remembered to be pasted with the
C-c < command. Repeating the command will paste multiple copies of
the date. This could be useful if you need to apply the same date to
A lot of functionality can be gained using dates, repeater intervals, deadline warnings, scheduled and deadline dates. Some uses are: Birthdays, Insurance Policies due dates, Home Maintenance tasks of a repetitive nature.
|C-c .||Prompt for active date|
|C-c !||Prompt for inactive date|
|C-c C-d||Enter a DEADLINE date|
|C-c C-s||Enter a SCHEDULED date|
|Repeat every Wednesday|
|Repeat on 1st day every month|
|Start warning 2 months before|
|Start warning 20 days before|
|Shift-RIGHT||Go forward a day|
|Shift-LEFT||Go backward a day|
|Shift-UP||Go to previous week|
|Shift-DOWN||Go to next week|
|<||Scroll calendar back 1 month|
|>||Scroll calendar forward 1 month|
|.||Go to Today|
|15 (Number)||Date of current month|
|Tue (Day name)||Date of nearest day specified|
|HH:MM||Enter a time|
|+2d ( or w, m, y)||Two days (weeks, months, years)|
|after today's date|
|++2d (or w, m, y)||Two days (weeks, months, years)|
|after the default date|
|+3tue||Third Tuesday of the month|
|(new in 5.13c)|
Date: 2007/10/24 (Tuesday) 10:39:49 PM