8.2.1 The date and 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 in fact accepts date/time information in a variety of formats. Generally, the information should start at the beginning of the string. Org mode finds whatever information is in there and derives 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 want to enter a date in the future: if you omit the month/year and the given day/month is before today, it assumes that you mean a future date¹. If the date has been automatically shifted into the future, the time prompt shows this with ‘(=>F)’.

For example, let’s assume that today is June 13, 2006. Here is how various inputs are 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 (default date or later)
‘`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 0: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—‘d’, ‘w’, ‘m’ or ‘y’—to indicate change in 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 is the Nth such day, e.g.:


‘`+0`’	⇒ today
‘`.`’	⇒ today
‘`+4d`’	⇒ four days from today
‘`+4`’	⇒ same as +4d
‘`+2w`’	⇒ two weeks from today
‘`++5`’	⇒ five days from default date
‘`+2tue`’	⇒ second Tuesday from now

The function understands English month and weekday abbreviations. If you want to use un-abbreviated 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². 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 is combined with the information entered at the prompt. You can control the calendar fully from the minibuffer:


`RET`	Choose date at point in calendar.
`mouse-1`	Select date by clicking on it.
`S-RIGHT`	One day forward.
`S-LEFT`	One day backward.
`S-DOWN`	One week forward.
`S-UP`	One week backward.
`M-S-RIGHT`	One month forward.
`M-S-LEFT`	One month backward.
`>`	Scroll calendar forward by one month.
`<`	Scroll calendar backward by one month.
`M-v`	Scroll calendar forward by 3 months.
`C-v`	Scroll calendar backward by 3 months.
`C-.`	Select today’s date³

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 is displayed live in the minibuffer⁴.

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.↩
If you do not need/want the calendar, configure the variable org-popup-calendar-for-date-prompt.↩
You can also use the calendar command . to jump to today’s date, but if you are inserting an hour specification for your timestamp, . will then insert a dot after the hour. By contrast, C-. will always jump to today’s date.↩
If you find this distracting, turn off the display with org-read-date-display-live.↩