6.1 Time stamps, deadlines and scheduling

A time stamp is a specification of a date (possibly with time) in a special format, either `<2003-09-16 Tue>' or `<2003-09-16 Tue 09:39>'¹. A time stamp can appear anywhere in the headline or body of an org-tree entry. Its presence allows entries to be shown on specific dates in the agenda (see Weekly/Daily agenda). We distinguish:

Plain time stamp

A simple time stamp just assigns a date/time to an item. This is just like writing down an appointment in a paper agenda, or like writing down an event in a diary, when you want to take note of when something happened. In the timeline and agenda displays, the headline of an entry associated with a plain time stamp will be shown exactly on that date.

          * Meet Peter at the movies <2006-11-01 Wed 19:15>
     

Inactive time stamp

Just like a plain time stamp, but with square brackets instead of angular ones. These time stamps are inactive in the sense that they do not trigger an entry to show up in the agenda.

          * Gillian comes late for the fifth time [2006-11-01 Wed]
     

Time stamp range

Two time stamps connected by `--' denote a time range. The headline will be shown on the first and last day of the range, and on any dates that are displayed and fall in the range. Here is an example:

          ** Meeting in Amsterdam
             <2004-08-23 Mon>--<2004-08-26 Thu>
     

Time stamp with SCHEDULED keyword

If a time stamp is preceded by the word `SCHEDULED:', it means you are planning to start working on that task on the given date. So this is not about recording an event, but about planning your work. The headline will be listed under the given date². In addition, a reminder that the scheduled date has passed will be present in the compilation for today, until the entry is marked DONE. I.e., the task will automatically be forwarded until completed.

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

Time stamp with DEADLINE keyword

If a time stamp is preceded by the word `DEADLINE:', the task (most likely a TODO item) is supposed to be finished on that date, and it will be listed then. In addition, the compilation for today will carry a warning about the approaching or missed deadline, starting org-deadline-warning-days before the due date, and continuing until the entry is marked DONE. An example:

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

Time stamp with CLOSED keyword

When org-log-done is non-nil, Org-mode will automatically insert a special time stamp each time a TODO entry is marked done (see Progress logging). This time stamp is enclosed in square brackets instead of angular brackets.

Time range with CLOCK keyword

When using the clock to time the work that is being done on specific items, time ranges preceded by the CLOCK keyword are inserted automatically into the file. The time stamps are enclosed in square brackets instead of angular brackets. See Clocking work time.