org: The date/time prompt
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(1). 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
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 implementations. 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(2). 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.
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(3).
---------- Footnotes ----------
(1) 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.
(2) If you don’t need/want the calendar, configure the variable
‘org-popup-calendar-for-date-prompt’.
(3) If you find this distracting, turn the display off with
‘org-read-date-display-live’.
Info Catalog
org: Creating timestamps
org: Creating timestamps
org: Custom time format