8.3 Deadlines and Scheduling

A timestamp may be preceded by special keywords to facilitate planning. Both the timestamp and the keyword have to be positioned immediately after the task they refer to.

‘DEADLINE’

Meaning: the task—most likely a TODO item, though not necessarily—is supposed to be finished on that date.

On the deadline date, the task is listed in the agenda. In addition, the agenda for today carries a warning about the approaching or missed deadline, starting org-deadline-warning-days before the due date, and continuing until the entry is marked as done. An example:

*** TODO write article about the Earth for the Guide
    DEADLINE: <2004-02-29 Sun>
    The editor in charge is [[bbdb:Ford Prefect]]

You can specify a different lead time for warnings for a specific deadlines using the following syntax. Here is an example with a warning period of 5 days ‘DEADLINE: <2004-02-29 Sun -5d>’. This warning is deactivated if the task gets scheduled and you set org-agenda-skip-deadline-prewarning-if-scheduled to t.

‘SCHEDULED’

Meaning: you are planning to start working on that task on the given date.

The headline is listed under the given date⁶⁵. In addition, a reminder that the scheduled date has passed is present in the compilation for today, until the entry is marked as done, i.e., the task is automatically forwarded until completed.

*** TODO Call Trillian for a date on New Years Eve.
    SCHEDULED: <2004-12-25 Sat>

If you want to delay the display of this task in the agenda, use ‘SCHEDULED: <2004-12-25 Sat -2d>’: the task is still scheduled on the 25th but will appear two days later. In case the task contains a repeater, the delay is considered to affect all occurrences; if you want the delay to only affect the first scheduled occurrence of the task, use ‘--2d’ instead. See org-scheduled-delay-days and org-agenda-skip-scheduled-delay-if-deadline for details on how to control this globally or per agenda.

Important: Scheduling an item in Org mode should not be understood in the same way that we understand scheduling a meeting. Setting a date for a meeting is just a simple appointment, you should mark this entry with a simple plain timestamp, to get this item shown on the date where it applies. This is a frequent misunderstanding by Org users. In Org mode, scheduling means setting a date when you want to start working on an action item.

You may use timestamps with repeaters in scheduling and deadline entries. Org mode issues early and late warnings based on the assumption that the timestamp represents the nearest instance of the repeater. However, the use of diary expression entries like

<%%(diary-float t 42)>

in scheduling and deadline timestamps is limited. Org mode does not know enough about the internals of each function to issue early and late warnings. However, it shows the item on each day where the expression entry matches.