55
Chapter 8: Dates and times
73
8 Dates and times
To assist project planning, TODO items can be labeled with a date and/or a time. The
specially formatted string carrying the date and time information is called a timestamp in
Org mode. This may be a little confusing because timestamp is often used to indicate when
something was created or last changed. However, in Org mode this term is used in a much
wider sense.
8.1 Timestamps, deadlines, and scheduling
Atimestamp is a specification of a date (possibly with a time or a range of times) in a
special format, either ‘<2003-09-16 Tue>’
1
or ‘<2003-09-16 Tue 09:39>’ or ‘<2003-09-16
Tue 12:00-12:30>’
2
. A timestamp can appear anywhere in the headline or body of an Org
tree entry. Its presence causes entries to be shown on specific dates in the agenda (see
Section 10.3.1 [Weekly/daily agenda], page 102). Wedistinguish:
Plain timestamp; Event; Appointment
Asimple timestamp just assigns a date/time to an item. This is just like writing
down an appointment or event in a paper agenda. In the timeline and agenda
displays, the headline of an entry associated with a plain timestamp will be
shown exactly on that date.
* Meet Peter at the movies
<2006-11-01 Wed 19:15>
* Discussion on climate change
<2006-11-02 Thu 20:00-22:00>
Timestamp with repeater interval
Atimestamp may contain a repeater interval, indicating that it applies not only
on the given date, but again and again after a certain interval of N days (d),
weeks (w), months (m), or years (y). The following will show up in the agenda
every Wednesday:
* Pick up Sam at school
<2007-05-16 Wed 12:30 +1w>
Diary-style sexp entries
For more complex date specifications, Org mode supports using the special sexp
diary entries implemented in the Emacs calendar/diary package
3
.For example
with optional time
1
In this simplest form, the day name is optional when you type the date yourself. However, any dates
inserted or modified by Org will add that day name, for reading convenience.
2
This is inspired by the standard ISO 8601 date/time format. To use an alternative format, see
Section 8.2.2 [Custom time format], page 77.
3
When working with the standard diary sexp functions, you need to be very careful with the order of
the arguments. That order depends evilly on the variable calendar-date-style (or, for older Emacs
versions, european-calendar-style). For example, to specify a date December 1, 2005, the call might
look like (diary-date 12 1 2005) or (diary-date 1 12 2005) or (diary-date 2005 12 1), depending on
the settings. This has been the source of much confusion. Org mode users can resort to special versions
of these functions like org-date or org-anniversary. These work just like the corresponding diary-
functions, but with stable ISO order of arguments (year, month, day) wherever applicable, independent
of the value of calendar-date-style.
VB.NET PDF - Convert PDF with VB.NET WPF PDF Viewer Create PDF from Text. PDF Export. Convert PDF to Word to PDF. Image: Remove Image from PDF Page. Image Edit Bookmark. Metadata: Edit, Delete Metadata. Form Process
how to save filled out pdf form in reader; can reader edit pdf forms
52
Chapter 8: Dates and times
74
* 22:00-23:00 The nerd meeting on every 2nd Thursday of the month
<%%(diary-float t 4 2)>
Time/Date range
Two timestamps connected by ‘--’ denote a 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>
Inactive timestamp
Just like a plain timestamp, but with square brackets instead of angular ones.
These timestamps 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]
8.2 Creating timestamps
For Orgmode to recognizetimestamps, they needto be inthe specific format. Allcommands
listed below produce timestamps in the correct format.
C-c .
org-time-stamp
Prompt for a date and insert a corresponding timestamp. When the cursor is
at an existing timestamp in the buffer, the command is used to modify this
timestamp instead of inserting a new one. When this command is used twice
in succession, a time range is inserted.
C-c !
org-time-stamp-inactive
Like C-c ., but insert an inactive timestamp that will not cause an agenda
entry.
C-u C-c .
C-u C-c ! Like C-c . and C-c !, but use the alternative format which contains date and
time. The default time can be rounded to multiples of 5 minutes, see the option
org-time-stamp-rounding-minutes.
C-c C-c
Normalize timestamp, insert/fix day name if missing or wrong.
C-c <
org-date-from-calendar
Insert a timestamp corresponding to the cursor date in the Calendar.
C-c >
org-goto-calendar
Access the Emacs calendar for the current date. If there is a timestamp in the
current line, go to the corresponding date instead.
C-c C-o
org-open-at-point
Access the agenda for the date given by the timestamp or -range at point (see
Section 10.3.1 [Weekly/daily agenda], page 102).
S-left
org-timestamp-down-day
S-right
org-timestamp-up-day
Change date at cursor by one day. These key bindings conflict with shift-
selection and related modes (seeSection15.10.2[Conflicts],page234).
69
Chapter 8: Dates and times
75
S-up
org-timestamp-up
S-down
org-timestamp-down-down
Change the item under the cursor in a timestamp. The cursor can be on a year,
month, day, hour or minute. When the timestamp contains a time range like
‘15:30-16:30’, modifying the first time will also shift the second, shifting the
time block with constant length. To change the length, modify the second time.
Note that if the cursor is in a headline and not at a timestamp, these same keys
modify the priority of an item. (seeSection5.4[Priorities],page55). The key
bindings also conflict with shift-selection and related modes (seeSection15.10.2
[Conflicts], page 234).
C-c C-y
org-evaluate-time-range
Evaluate a time range by computing the difference between start and end.
With a prefix argument, insert result after the time range (in a table: into the
following column).
8.2.1 The date/time prompt
When Org mode prompts for a date/time, the default is shown in default date/time format,
and the prompt therefore seems to ask for a specific format. But it will in fact accept
date/time information in a variety of formats. Generally, the information should start at
the beginning of the string. Org mode will find whatever information is in there and derive
anything you have not specified from the default date and time. The default is usually
the current date and time, but when modifying an existing timestamp, or when entering
the second stamp of a range, it is taken from the stamp in the buffer. When filling in
information, Org mode assumes that most of the time you will want to enter a date in the
future: if you omit the month/year and the given day/month is before today, it will assume
that you mean a future date
4
. If the date has been automatically shifted into the future,
the time prompt will show this with ‘(=>F).’
For example, let’s assume that today is June 13, 2006. Here is how various inputs will
be interpreted, the items filled in by Org mode are in bold.
3-2-5
) 2003-02-05
2/5/3
)
2003-02-05
14
) 2006-06-14
12
)
2006-07-12
2/5
) 2007-02-05
Fri
)
nearest Friday after the default date
sep 15
) 2006-09-15
feb 15
) 2007-02-15
sep 12 9
) 2009-09-12
12:45
) 2006-06-13 12:45
22 sept 0:34 ) 2006-09-22 00:34
w4
) ISO week for of the current year 2006
2012 w4 fri
)
Friday of ISO week 4 in 2012
2012-w04-5
) Same as above
4
See the variable org-read-date-prefer-future. You may set that variable to the symbol time to even
make a time before now shift the date to tomorrow.
71
Chapter 8: Dates and times
76
Furthermore you can specify a relative date by giving, as the first thing in the input: a
plus/minus sign, a number and a letter ([hdwmy]) to indicate change in hours, days, weeks,
months, or years. With a single plus or minus, the date is always relative to today. With a
double plus or minus, it is relative to the default date. If instead of a single letter, you use
the abbreviation of day name, the date will be the Nth such day, e.g.:
+0
) today
.
) today
+4d
) four days from today
+4
) same as above
+2w
) two weeks from today
++5
) five days from default date
+2tue
) second Tuesday from now
-wed
) last Wednesday
The function understands English month and weekday abbreviations. If you want to use
unabbreviated names and/or other languages, configure the variables parse-time-months
and parse-time-weekdays.
Not all dates can be represented in a given Emacs implementation. By default Org mode
forces dates into the compatibility range 1970–2037 which works on all Emacs implemen-
tations. If you want to use dates outside of this range, read the docstring of the variable
org-read-date-force-compatible-dates.
You can specify a time range by giving start and end times or by giving a start time
and a duration (in HH:MM format). Use one or two dash(es) as the separator in the former
case and use ’+’ as the separator in the latter case, e.g.:
11am-1:15pm
) 11:00-13:15
11am--1:15pm
)
same as above
11am+2:15
) same as above
Parallel to the minibuffer prompt, a calendar is popped up
5
. When you exit the date
prompt, either by clicking on a date in the calendar, or by pressing RET, the date selected in
the calendar will be combined with the information entered at the prompt. You can control
the calendar fully from the minibuffer:
RET
Choose date at cursor in calendar.
mouse-1
Select date by clicking on it.
S-right/left
One day forward/backward.
S-down/up
One week forward/backward.
M-S-right/left One month forward/backward.
> / <
Scroll calendar forward/backward by one month.
M-v / C-v
Scroll calendar forward/backward by 3 months.
M-S-down/up
Scroll calendar forward/backward by one year.
The actions of the date/time prompt may seem complex, but I assure you they will grow
on you, and you will start getting annoyed by pretty much any other way of entering a
date/time out there. To help you understand what is going on, the current interpretation
of your input will be displayed live in the minibuffer
6
.
5
If you don’t need/want the calendar, configure the variable org-popup-calendar-for-date-prompt.
6
If you find this distracting, turn the display off with org-read-date-display-live.
45
Chapter 8: Dates and times
77
8.2.2 Custom time format
Org mode uses the standard ISO notation for dates and times as it is defined in ISO 8601.
If you cannot get used to this and require another representation of date and time to keep
you happy, you can get it by customizing the options org-display-custom-times and
org-time-stamp-custom-formats.
C-c C-x C-t
org-toggle-time-stamp-overlays
Toggle the display of custom formats for dates and times.
Org mode needs the default format for scanning, so the custom date/time format does not
replace the default format—instead it is put over the default format using text properties.
This has the following consequences:
You cannot place the cursor onto a timestamp anymore, only before or after.
The S-up/down keys can no longer be used to adjust each component of a timestamp.
If the cursor is at the beginning of the stamp, S-up/down will change the stamp by one
day, just like S-left/right. At the end of the stamp, the time will be changed by one
minute.
If the timestampcontains a range of clock times or a repeater, these will not be overlaid,
but remain in the buffer as they were.
When you delete a timestamp character-by-character, it will only disappear from the
buffer after all (invisible) characters belonging to the ISO timestamp have been re-
moved.
If the custom timestamp format is longer than the default and you are using dates in
tables, table alignment will be messed up. If the custom format is shorter, things do
work as expected.
8.3 Deadlines and scheduling
Atimestamp may be preceded by special keywords to facilitate planning:
DEADLINE
Meaning: the task (most likely a TODO item, though not necessarily) is sup-
posed to be finished on that date.
On the deadline date, the task will be listed in the agenda. In addition, the
agenda for today willcarry a warning about the approaching or missed deadline,
startingorg-deadline-warning-days before the due date,and continuinguntil
the entry is marked 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 deadline us-
ing 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.
55
Chapter 8: Dates and times
78
The headline will be listed under the given date
7
. 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>
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 meet-
ing 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
will issue early and late warnings based on the assumption that the timestamp repre-
sents the nearest instance of the repeater. However, the use of diary sexp entries like
<%%(diary-float t 42)> in scheduling and deadline timestamps is limited. Org mode
does not know enough about the internals of each sexp function to issue early and late
warnings. However, it will show the item on each day where the sexp entry matches.
8.3.1 Inserting deadlines or schedules
The following commands allow you to quickly insert
8
adeadline or to schedule an item:
C-c C-d
org-deadline
Insert ‘DEADLINE’keywordalong with a stamp. The insertionwill happen inthe
line directly following the headline. Any CLOSED timestamp will be removed.
When called with a prefix arg, an existing deadline will be removed from the
entry. Depending on the variable org-log-redeadline
9
,a note will be taken
when changing an existing deadline.
C-c C-s
org-schedule
Insert ‘SCHEDULED’ keyword along with a stamp. The insertion will happen
in the line directly following the headline. Any CLOSED timestamp will be
removed. When called with a prefix argument, remove the scheduling date
7
It will still be listed on that date after it has been marked DONE. If you don’t like this, set the variable
org-agenda-skip-scheduled-if-done.
8
The ‘SCHEDULED’ and ‘DEADLINE’ dates are inserted on the line right below the headline. Don’t put any
text between this line and the headline.
9
with corresponding #+STARTUP keywords logredeadline, lognoteredeadline, and nologredeadline
53
Chapter 8: Dates and times
79
from the entry. Depending on the variable org-log-reschedule
10
,a note will
be taken when changing an existing scheduling time.
C-c / d
org-check-deadlines
Create a sparse tree with all deadlines that are either past-due, or which will
become due within org-deadline-warning-days. With C-u prefix, show all
deadlines in the file. Witha numeric prefix,check that many days. For example,
C-1 C-c / d shows all deadlines due tomorrow.
C-c / b
org-check-before-date
Sparse tree for deadlines and scheduled items before a given date.
C-c / a
org-check-after-date
Sparse tree for deadlines and scheduled items after a given date.
Note that org-schedule and org-deadline supports setting the date by indicating a
relative time: e.g., +1d will set the date to the next day after today, and –1w will set the
date to the previous week before any current timestamp.
8.3.2 Repeated tasks
Some tasks need to be repeated again and again. Org mode helps to organize such tasks
using a so-called repeater in a DEADLINE, SCHEDULED, or plain timestamp. In the
following example
** TODO Pay the rent
DEADLINE: <2005-10-01 Sat +1m>
the +1m is a repeater; the intended interpretation is that the task has a deadline on <2005-
10-01> and repeats itself every (one) month starting from that time. You can use yearly,
monthly, weekly, daily and hourly repeat cookies by using the y/w/m/d/h letters. If you
need both a repeater and a special warning period in a deadline entry, the repeater should
come first and the warning period last: DEADLINE: <2005-10-01 Sat +1m -3d>.
Deadlines and scheduled items produce entries in the agenda when they are over-due,
so it is important to be able to mark such an entry as completed once you have done so.
When you mark a DEADLINE or a SCHEDULE with the TODO keyword DONE, it will
no longer produce entries in the agenda. The problem with this is, however, that then also
the next instance of the repeated entry will not be active. Org mode deals with this in the
following way: When you try to mark such an entry DONE (using C-c C-t), it will shift
the base date of the repeating timestamp by the repeater interval, and immediately set
the entry state back to TODO
11
.In the example above, setting the state to DONE would
actually switch the date like this:
** TODO Pay the rent
DEADLINE: <2005-11-01 Tue +1m>
To mark a task with a repeater as DONE, useC-- 1 C-c C-t (i.e., org-todo with anumeric
prefix argument of -1.)
10
with corresponding #+STARTUP keywords logreschedule, lognotereschedule, and nologreschedule
11
In fact, the target state is taken from, in this sequence, the REPEAT_TO_STATE property or the variable
org-todo-repeat-to-state. If neither of these is specified, the target state defaults to the first state of
the TODO state sequence.
Documents you may be interested
Documents you may be interested
