Dates and Times
A task list without dates tells you what to do but not when. Org attaches dates to entries with a single, compact notation, the timestamp, and then uses those timestamps everywhere: the agenda (Org’s combined calendar and task list, built from your files) reads them to build your day, the clock writes them to record your work, and capture templates insert them to record when an idea arrived.
This chapter explains the timestamp syntax first, then the commands that create and edit timestamps without typing them by hand, then the 2 planning keywords DEADLINE and SCHEDULED, and finally repeating tasks. The agenda, which is where most of these dates become visible, has its own chapter: Agenda Views. Recording working time is covered in Clocking, Effort and Timers.
All examples in this chapter assume that “today” is Thursday, 19 November 2026. The agenda lines and edited entries shown below were produced by Org 9.8.13 running in Emacs batch mode with the clock set to that date.
The timestamp: one notation for every date
In Org, a timestamp is a date, optionally followed by a time or a time range, written in a fixed format between angle brackets or square brackets. The word is broader than in everyday programming, where a timestamp usually records when something was created or modified. In Org, a timestamp can mark an appointment, a deadline, a planned start, a logged event, or an interval of work.
The format follows ISO 8601 order (year, month, day) with a day name for readability:
<2026-11-19 Thu>
<2026-11-19 Thu 14:00>
<2026-11-19 Thu 14:00-15:00>
The day name is optional when you type a timestamp yourself, but Org adds it whenever it inserts or modifies one. You will rarely type a timestamp by hand, because the commands described in the next section produce the correct format for you and also let you edit it with the arrow keys.
Active and inactive timestamps
The bracket type decides whether a timestamp influences the agenda.
| Form | Name | Effect on the agenda |
|---|---|---|
<2026-11-19 Thu> | active timestamp | The entry is shown on that date. |
[2026-11-19 Thu] | inactive timestamp | The entry is not shown. The date is only a record. |
Use an active timestamp when the date is a commitment that you want to see in your calendar. Use an inactive timestamp when the date is history: when you created a note, when a meeting took place, when a bug was first observed. Org itself writes inactive timestamps for logging (state changes, clock lines, refile notes) so that years of records do not flood your agenda.
The following file contains one entry of each kind:
* Design review with the platform team
<2026-11-19 Thu 14:00-15:00>
* Lunch with Ana
[2026-11-19 Thu]
In the agenda for 19 November, only the design review appears. The lunch remains a dated note, which you can still find with a search.
Plain timestamps, ranges and repeaters
A timestamp that is not preceded by a planning keyword is a plain timestamp. It works like an entry in a paper diary: the headline is shown in the agenda on exactly that date and nowhere else. An entry may contain several plain timestamps, for example one for each day a recurring workshop takes place.
There are 2 ways to express duration:
- A time range inside a single timestamp, written with one hyphen between 2 times:
<2026-11-19 Thu 14:00-15:00>. - A date range, made of 2 timestamps joined by a double hyphen:
<2026-11-11 Wed>--<2026-11-13 Fri>. The agenda shows the entry on every day of the range and labels it with its position, such as(2/3)on the second day.
A repeater is a suffix such as +1w that makes a timestamp recur. The letter selects the unit: h (hours), d (days), w (weeks), m (months) or y (years). The following entry appears in the agenda every Wednesday from its start date on:
* Pick up the children from school
<2026-11-18 Wed 15:30 +1w>
Repeaters behave differently when they appear in a deadline or a scheduled date of a task, because then marking the task done moves the date. That case is covered in Repeating tasks below. Org never repeats inactive timestamps.
Diary-style expressions
Some dates cannot be expressed with a fixed interval: “the second Thursday of every month”, or “every year on a birthday”. For these, Org accepts a diary sexp, an Emacs Lisp expression from the Emacs calendar package, inside a timestamp. The form is <%%(EXPRESSION)>, optionally followed by a time:
* Team retrospective
<%%(diary-float t 4 2) 16:00-17:00>
* Conference trip
<2026-11-11 Wed>--<2026-11-13 Fri>
* Birthdays
%%(org-anniversary 1990 11 12) Maria Silva turns %d
(diary-float t 4 2) means “any month, weekday 4 (Thursday), the 2nd occurrence”. The last line shows a second form: a sexp at the very beginning of a line, outside any brackets, followed by text. This form is evaluated in the same way, and %d is replaced by the number of years. The agenda for Thursday, 12 November 2026, generated from this file, reads:
Day-agenda (W46):
Thursday 12 November 2026
sexp: 16:00-17:00 Team retrospective
sexp: (2/3): Conference trip
sexp: Maria Silva turns 36
The standard diary- functions read their date arguments in an order that depends on the variable calendar-date-style, which makes shared files fragile. Org provides org-date, org-anniversary, org-cyclic and org-block, which work like their diary counterparts but always take year, month and day in ISO order. Prefer them in Org files.
Diary sexps are powerful, but Org cannot reason about them as it does about ordinary dates. In particular, when a sexp is used in a deadline, Org shows the entry on each matching day but cannot issue early warnings, because it does not know when the next match will occur.
Creating and editing timestamps
Typing <2026-11-19 Thu 14:00> by hand is slow and error prone. Org offers a family of commands that prompt for a date, insert the timestamp in the correct format, and later adjust it in place.
Inserting a timestamp
| Key | Command | Purpose |
|---|---|---|
C-c . | org-timestamp | Prompt for a date and insert an active timestamp. On an existing timestamp, edit it. |
C-c ! | org-timestamp-inactive | Same, but insert an inactive timestamp. |
C-u C-c . | org-timestamp | Include a time of day. |
C-u C-u C-c . | org-timestamp | Insert the current date and time without prompting. |
C-c . twice | org-timestamp | Pressed again directly after insertion, create a date range. |
When you use the prefix argument to include the current time, Org can round the minutes; the variable org-time-stamp-rounding-minutes controls this.
A pair of commands connects timestamps with the Emacs calendar. C-c > (org-goto-calendar) opens the calendar at the date of the timestamp on the current line, or at today. C-c < (org-date-from-calendar) works the other way: typed in the Org buffer, it inserts a timestamp for the date that is selected in the calendar window.
The date prompt
The date prompt is where Org saves you the most time. It looks as if it expects a full date, but it accepts fragments and fills in the rest from a default date, which is normally today (or the existing timestamp when you edit one). A small calendar opens at the same time, and the minibuffer shows how Org currently interprets your input.
Org assumes that you are planning ahead. If you type a day or a month that has already passed this year, it moves the date into the future (controlled by org-read-date-prefer-future). The following table shows real interpretations with today set to Thursday, 19 November 2026:
| Input | Result | Why |
|---|---|---|
14 | <2026-12-14 Mon> | Day 14 of this month has passed, so next month. |
12 | <2026-12-12 Sat> | Same rule. |
fri | <2026-11-20 Fri> | The nearest Friday, today or later. |
dec 3 | <2026-12-03 Thu> | Month name and day. |
2/5 | <2027-02-05 Fri> | Month/day; February 5 has passed in 2026, so 2027. |
w48 | <2026-11-23 Mon> | ISO week 48 of the current year. |
2027-01-15 9:00 | <2027-01-15 Fri 09:00> | Full ISO date with time. |
15:00 | <2026-11-19 Thu 15:00> | A time alone means today. |
11am-1:15pm | <2026-11-19 Thu 11:00-13:15> | A time range. |
11am+2:15 | <2026-11-19 Thu 11:00-13:15> | A start time plus a duration. |
Relative dates are often even faster. Start the input with a sign, a number and a unit letter:
| Input | Result | Meaning |
|---|---|---|
+3d | <2026-11-22 Sun> | 3 days from today. |
+2w | <2026-12-03 Thu> | 2 weeks from today. |
+1m | <2026-12-19 Sat> | 1 month from today. |
+2tue | <2026-12-01 Tue> | The second Tuesday from today. |
+2h | <2026-11-19 Thu 12:30> | 2 hours from now (the run used 10:30). |
A single sign (+3d) counts from today; a double sign (++3d) counts from the default date, which is useful when you edit an existing timestamp and want to move it relative to its current value. . or +0 means today.
The calendar can be controlled without leaving the minibuffer. S-LEFT and S-RIGHT move by one day, S-UP and S-DOWN by one week, M-S-LEFT and M-S-RIGHT by one month, and < and > scroll the calendar. RET accepts the date at point in the calendar, combined with whatever you typed. C-. jumps back to today.
There are 2 limits to keep in mind. The prompt understands English month and weekday abbreviations; to use full names or another language, set parse-time-months and parse-time-weekdays. And by default, Org restricts dates to the range 1970 to 2037, which every Emacs build can represent; the docstring of org-read-date-force-compatible-dates explains how to lift this restriction.
Changing a timestamp in place
Once a timestamp exists, you can adjust it with the shifted arrow keys while point is on it:
S-LEFTandS-RIGHT(org-timestamp-down-day,org-timestamp-up-day) move the date by one day.S-UPandS-DOWN(org-timestamp-up,org-timestamp-down) change the component under point: year, month, day, hour or minute. On a bracket, they toggle between active and inactive.
If the timestamp contains a time range such as 14:00-15:00, changing the start time moves the end time too, so the length of the block stays the same. To change the length, edit the end time. Note that on a headline but outside a timestamp, the same keys change the priority of the entry; they also conflict with shift-selection; see Org Beyond the Basics for ways to resolve such conflicts with other packages.
The set is completed by 2 further commands:
C-c C-con a timestamp normalizes it, for example by adding or correcting the day name after you typed a date by hand.C-c C-y(org-evaluate-time-range) computes the length of a range. With a prefix argument, it inserts the result after the range.
Displaying dates in a different format
Org always stores ISO dates, because it needs one predictable format to parse. If you prefer to read dates differently, you can overlay a custom format: set org-display-custom-times to t and describe the format in org-timestamp-custom-formats, a pair of format-time-string patterns for dates without and with a time. C-c C-x C-t (org-toggle-timestamp-overlays) switches the overlay on and off.
(setq org-display-custom-times t)
(setq org-timestamp-custom-formats
'("%d %b %Y %a" . "%d %b %Y %a %H:%M"))
The overlay changes only the display, which has side effects. Point can no longer enter the timestamp, so S-UP and S-DOWN cannot select individual components, and table columns that contain dates may lose alignment if the custom format is longer than the ISO one. For most users the ISO format becomes familiar quickly, and it sorts correctly as plain text.
Deadlines and scheduled dates
Plain timestamps describe events. Tasks need something different: a date by which the work must be finished, and a date on which you intend to start. Org expresses these with 2 planning keywords, DEADLINE and SCHEDULED, placed on the line directly below the headline (the planning line):
* TODO Submit the conference talk proposal
DEADLINE: <2026-11-24 Tue>
* TODO Refactor the billing module
SCHEDULED: <2026-11-17 Tue>
Do not put any other text between the headline and the planning line; Org only recognizes the keywords in that position. A task can carry both keywords on the same line.
The important difference from a plain timestamp is that both keywords make Org follow the entry over time. A plain timestamp appears on one day and is forgotten. A deadline warns you in advance and stays visible after the date has passed; a scheduled task reappears every day until you mark it done.
What a deadline means
A DEADLINE states that the task should be finished on that date. In the agenda for today, Org starts warning about the deadline org-deadline-warning-days days in advance (14 by default). On the due date the entry is labeled Deadline:, and after it the entry keeps appearing on today’s agenda with the number of days it is overdue, until you mark it done.
You can change the warning period for a single deadline by appending a negative offset to the timestamp. DEADLINE: <2026-11-30 Mon -3d> starts warning only 3 days in advance, which suits small tasks that do not need 2 weeks of reminders.
What scheduling means
A SCHEDULED date states when you plan to start working on a task. The agenda lists the entry on that date with the label Scheduled:. If the day passes and the task is still open, Org carries it forward: it appears on every following day as Sched.Nx:, where N counts the days since the scheduled date.
A common mistake is to schedule meetings. A meeting is an appointment at a fixed time; give it a plain timestamp. Scheduling in Org means “this is when I intend to begin”, and the carry-forward behavior only makes sense for work that remains to be done.
Sometimes you want to schedule a task but hide it for a few days. A negative offset on a scheduled date does that: SCHEDULED: <2026-11-18 Wed -2d> keeps the scheduled date on the 18th but only shows the task from the 20th. For a repeating timestamp, -2d delays every occurrence, while --2d delays only the first one. The global default for this delay is org-scheduled-delay-days.
Seeing the rules in the agenda
The following file combines the cases discussed so far. It was loaded into the agenda with 3 different “today” values.
* TODO Submit the conference talk proposal
DEADLINE: <2026-11-24 Tue>
* TODO Renew the TLS certificate
DEADLINE: <2026-11-30 Mon -3d>
* TODO Send the quarterly invoice
DEADLINE: <2026-11-16 Mon>
* TODO Refactor the billing module
SCHEDULED: <2026-11-17 Tue>
* TODO Review the hiring rubric
SCHEDULED: <2026-11-18 Wed -2d>
* Design review with the platform team
<2026-11-19 Thu 14:00-15:00>
* Lunch with Ana
[2026-11-19 Thu]
On Thursday, 19 November:
Day-agenda (W47):
Thursday 19 November 2026
plan: 14:00-15:00 Design review with the platform team
plan: Sched. 2x: TODO Refactor the billing module
plan: 3 d. ago: TODO Send the quarterly invoice
plan: In 5 d.: TODO Submit the conference talk proposal
On Friday, 20 November, the delayed review appears for the first time:
Day-agenda (W47):
Friday 20 November 2026
plan: Sched. 3x: TODO Refactor the billing module
plan: Sched. 2x: TODO Review the hiring rubric
plan: 4 d. ago: TODO Send the quarterly invoice
plan: In 4 d.: TODO Submit the conference talk proposal
On Friday, 27 November, the certificate deadline enters its 3-day warning period:
Day-agenda (W48):
Friday 27 November 2026
plan: Sched.10x: TODO Refactor the billing module
plan: Sched. 9x: TODO Review the hiring rubric
plan: 11 d. ago: TODO Send the quarterly invoice
plan: 3 d. ago: TODO Submit the conference talk proposal
plan: In 3 d.: TODO Renew the TLS certificate
The lunch never appears, because its timestamp is inactive. The design review appears only on the 19th, because a plain timestamp does not follow you. The deadline on the 24th was first announced on 10 November (In 14 d.:), exactly 14 days before; on the 9th it was not yet listed.
Figure 10.1: Warning periods appear before a deadline, delays postpone a scheduled task, and both kinds of entry stay on today’s agenda until the task is done.
Several variables refine this behavior. org-agenda-skip-deadline-prewarning-if-scheduled suppresses the early warning for a task that is already scheduled, on the reasoning that you have planned when to do it. org-agenda-skip-scheduled-delay-if-deadline ignores the scheduled delay when the task also has a deadline. org-agenda-skip-scheduled-if-done hides scheduled entries on their date once they are done. The agenda chapter explains how to apply such settings to individual views.
Commands for deadlines and scheduling
| Key | Command | Purpose |
|---|---|---|
C-c C-d | org-deadline | Insert or change the deadline. With C-u, remove it. |
C-c C-s | org-schedule | Insert or change the scheduled date. With C-u, remove it. |
C-c / d | org-check-deadlines | Show a sparse tree of deadlines that are overdue or within the warning period. |
C-c / b | org-check-before-date | Sparse tree of deadlines and scheduled dates before a given date. |
C-c / a | org-check-after-date | Sparse tree of deadlines and scheduled dates after a given date. |
C-c C-d and C-c C-s use the same date prompt as C-c ., so relative input works: +1d schedules a task for tomorrow, and ++1w moves an existing date one week later than its current value. Both commands write the planning line directly below the headline and remove any CLOSED timestamp, since a task with a new date is evidently not closed.
When you move a date that was already set, Org can record the change. The variables org-log-reschedule and org-log-redeadline (both nil by default) can be set to time to log a timestamp or to note to ask for a short explanation. The same choices exist as #+STARTUP options per file: logreschedule, lognotereschedule, nologreschedule, and logredeadline, lognoteredeadline, nologredeadline. A history of postponements is useful during a review, because a task that has been rescheduled 6 times is probably not the right task.
C-c / d takes a numeric prefix to change the horizon. C-1 C-c / d shows the deadlines due by tomorrow; C-u C-c / d shows every deadline in the file. A sparse tree is a view of the outline that shows only the matching entries and the headings above them; it is introduced in Document Structure.
Repeating tasks
Many tasks return: paying the rent, renewing a certificate, writing a weekly report. Creating a new entry each time would be tedious, and a plain repeating timestamp does not help, because a task needs to be marked done. Org solves this with a repeater on the DEADLINE or SCHEDULED timestamp.
* TODO Pay the rent
DEADLINE: <2026-10-01 Thu +1m>
When you mark this task done with C-c C-t, Org does not leave it in the DONE state. It moves the timestamp forward by the repeater interval and immediately sets the task back to its open state, so the next occurrence is ready. A record of the completion is kept in the entry.
flowchart LR A["TODO with repeater"] -->|"C-c C-t DONE"| B["Shift date by interval"] B --> C["Set LAST_REPEAT property"] C --> D["Log the state change"] D -->|"state reset"| A
Figure 10.2: Marking a repeating task done records the completion and returns the same entry to an open state with its next date.
The state that the task returns to is, in order of precedence: the REPEAT_TO_STATE property of the entry (a property is a key-value pair stored in the PROPERTIES drawer, a folded block between :PROPERTIES: and :END: below the headline), the value of org-todo-repeat-to-state if it is a string, the previous state if that variable is t, and otherwise the first state of the TODO sequence. If an entry contains several repeating timestamps, all of them are shifted. To close a repeating task for good, use C-- 1 C-c C-t (a numeric prefix of -1), which marks it done without repeating.
3 kinds of repeater
The repeater +1m shifts the date by exactly one interval, starting from the old date. That is correct for the rent: if you are 3 months behind, you owe 3 payments, and the task should stay overdue. For other tasks, catching up makes no sense. If you forgot to call a relative for 3 weeks, you do not want to call 3 times in one day. And some tasks should recur a fixed interval after you last did them, wherever the calendar stood.
Org has a repeater type for each of these situations:
| Repeater | Next date after marking done | Typical use |
|---|---|---|
+1m | Old date plus exactly 1 interval, even if that is still in the past. | Obligations that accumulate: rent, invoices. |
++1w | Old date plus as many intervals as needed to reach the future; the weekday is preserved. | Habits tied to a day: a weekly call on Sunday. |
.+1m | Today plus 1 interval. | Maintenance relative to the last action: replacing a filter. |
The following file was marked done with C-c C-t on Thursday, 19 November 2026 at 10:30:
* TODO Pay the rent
DEADLINE: <2026-10-01 Thu +1m>
* TODO Call Mother
SCHEDULED: <2026-10-25 Sun ++1w>
* TODO Replace the water filter
SCHEDULED: <2026-09-01 Tue .+1m>
Org produced this result:
* TODO Pay the rent
DEADLINE: <2026-11-01 Sun +1m>
:PROPERTIES:
:LAST_REPEAT: [2026-11-19 Thu 10:30]
:END:
- State "DONE" from "TODO" [2026-11-19 Thu 10:30]
* TODO Call Mother
SCHEDULED: <2026-11-22 Sun ++1w>
:PROPERTIES:
:LAST_REPEAT: [2026-11-19 Thu 10:30]
:END:
- State "DONE" from "TODO" [2026-11-19 Thu 10:30]
* TODO Replace the water filter
SCHEDULED: <2026-12-19 Sat .+1m>
:PROPERTIES:
:LAST_REPEAT: [2026-11-19 Thu 10:30]
:END:
- State "DONE" from "TODO" [2026-11-19 Thu 10:30]
Read the 3 dates carefully. The rent moved by one month, from 1 October to 1 November, and is therefore still overdue: one payment is still missing. The call moved from 25 October in whole weeks until it reached the future and landed on Sunday, 22 November. The filter moved to exactly one month after the day of completion.
For repeaters counted in days, weeks, months or years, Org compares whole days and ignores the time of day. A task with DEADLINE: <2026-11-15 Sun 20:00 ++1d>, marked done at 10:30 on 19 November, moved to <2026-11-20 Fri 20:00 ++1d>: the next occurrence is always after today, even though 20:00 today was still ahead. (The manual describes the same-day case differently; the result above is what Org 9.8.13 does.) Only hourly repeaters look at the clock: .+1h sets the next occurrence one hour after the moment you finish, and ++1h moves forward in whole hours until the time is in the future.
You can combine a repeater with a warning period on a deadline. The repeater must come first: DEADLINE: <2026-12-01 Tue +1m -3d>.
flowchart TD
Q1{"Does every missed occurrence still need doing?"} -->|yes| P["+ : fixed steps from the old date"]
Q1 -->|no| Q2{"Must it stay on the same weekday or time?"}
Q2 -->|yes| PP["++ : jump forward to the next future slot"]
Q2 -->|no| DP[".+ : count from the day you finish"]
Figure 10.3: Choose the repeater by asking whether missed occurrences matter and whether the calendar position matters.
Logging repetitions
Each completion adds the LAST_REPEAT property and, by default, a line with the state change and the time. This is governed by org-log-repeat, whose default value time records a timestamp; note also asks for a note, and nil records nothing. The #+STARTUP options logrepeat, lognoterepeat and nologrepeat set the same behavior per file. If the log lines clutter your entries, set org-log-into-drawer to t so that they go into a LOGBOOK drawer (the same drawer the clock uses, see Clocking, Effort and Timers). State logging in general is described in TODO Items, which also covers habits, a special kind of repeating task with a consistency graph.
Mixing scheduled and deadline repeaters
A task can have both a scheduled date and a deadline. If only the scheduled date repeats, you may want the repetitions to stop after the deadline; set org-agenda-skip-scheduled-repeats-after-deadline to t. A scheduled date without a repeater is removed when a repeating task is marked done, because it referred only to the occurrence you have just finished. If both dates should advance together, give both the same repeater.
Copies instead of repeaters
A repeater keeps a single entry and moves its date. Sometimes you want separate entries instead, for example one entry per session of a 6-week course, each with its own notes. C-c C-x c (org-clone-subtree-with-time-shift) creates a number of copies of the current subtree (the heading with everything below it) and shifts the timestamps in each copy by an interval that you specify. This is described with the other structure-editing commands in Document Structure.
Choosing the right kind of date
The rules above lead to a short set of guidelines that work for most task systems:
| Situation | Use |
|---|---|
| A meeting, a call, a flight | Plain active timestamp, with a time. |
| A note about when something happened | Inactive timestamp. |
| Work that must be finished by a date | DEADLINE, with a shorter warning period for small tasks. |
| Work you intend to start on a date | SCHEDULED, with a delay if you want it hidden until later. |
| Recurring obligation | Repeater on the planning timestamp, +, ++ or .+ as in Figure 10.3. |
| Irregular calendar rules | Diary sexp such as org-anniversary or diary-float. |
Keep deadlines for real deadlines. If every task carries one, the warnings lose their meaning, and the agenda becomes a wall of red. The weekly review described in Putting It Together is a good moment to check that scheduled dates are still realistic.
Further reading
- Dates and Times
- Timestamps
- Creating Timestamps
- The date/time prompt
- Custom time format
- Deadlines and Scheduling
- Inserting deadline/schedule
- Repeated tasks
- Source:
lisp/org.el(org-read-date,org-deadline,org-schedule,org-auto-repeat-maybe)