Dates and times

Org keeps dates in the text itself, as timestamps like <2026-11-16 Mon>. A timestamp can carry a time, a time range, a repeater and a warning period; two of them joined by -- make a date range. Put one after SCHEDULED: or DEADLINE: under a headline and the entry becomes a task for that day. The agenda (09-agenda.org) collects them from all your files.

This file walks through everything org.nvim does with dates: the syntax, inserting and editing timestamps, the calendar popup, the date input language, shifting dates, computing durations and diary sexps.

• The file starts folded (#+STARTUP: overview). Put the cursor on a heading and press <Tab> to open it, <S-Tab> to cycle the whole file.
• Lines starting with Try: are exercises, Expect: says what you should see afterwards. Lines starting with # are comments about the example next to them.
• Nothing breaks if you make a mess: u undoes, and git checkout examples/07-dates.org restores the file.
• <prefix> means <leader>o (the default mappings.prefix). g? lists every key of the buffer. Emacs keys (C-c ., C-c C-s, …) work too; they are written <C-c>. and <C-c><C-s> here.
• A count is a number typed before a key: 4<prefix>i. means press 4, then <leader>oi.. Counts stand in for Emacs's C-u (4) and C-u C-u (16).

Start Neovim from the repository root with the bundled init file, so the agenda sees these files and your own notes are untouched:

nvim -u examples/minimal_init.lua examples/07-dates.org

examples/minimal_init.lua sets agenda_files to examples/*.org (plus a scratch directory under stdpath("state") for captures), and adds a few capture templates and custom agenda commands. The live timestamps of this file therefore show up in your agenda while you work through it.

Two conventions of this file:

1. Today is assumed to be Mon 2026-09-28. Every "you get" date was computed by org.nvim on that day. If you read this later, relative inputs (+3d, fri, …) give dates relative to your today: the rule stays the same, only the result moves.
2. Every active <...> timestamp in the text of a file is an agenda entry, even inside a list or a table (as in Emacs, only comments, : = lines, keywords and src, example, export and comment blocks are left out). So that the expected results written in this file don't show up in your agenda, *an expected active timestamp is written without its angle brackets*: "Expect: =SCHEDULED: 2026-10-02 Fri" means the buffer shows SCHEDULED: followed by the date in <>. Exercises that don't need the agenda use inactive [...] timestamps: every key works the same on both kinds.

A timestamp is a date in angle or square brackets:

<2026-11-16 Mon>          active: shows up in the agenda
[2026-11-16 Mon]          inactive: a plain note of when something happened

• The date is always YYYY-MM-DD. The weekday name after it is only for you to read: org.nvim writes it, but ignores it when reading, so a wrong or missing weekday does not change the date (see "Normalizing" below).
• Active <...> timestamps anywhere in an entry (headline, body) make the entry appear in the agenda on that day.
• Inactive [...] timestamps never do. Use them for "created on", "last contacted", log notes, and so on. CLOCK lines and CLOSED use them.
• The rest (time, repeater, warning) goes inside the brackets, after the weekday, separated by spaces.

The full shape, every part after the weekday optional:

<2026-12-03 Thu 10:00-11:30 +1w -2d>
 |          |   |     |     |   `-- warning / delay period
 |          |   |     |     `------ repeater
 |          |   |     `------------ end time (a time range)
 |          |   `------------------ start time, 24-hour HH:MM
 |          `---------------------- weekday name (informational)
 `--------------------------------- date

Add a time after the weekday, in 24-hour HH:MM. Add -HH:MM for an end time on the same day:

<2026-11-19 Thu 09:30>         at 09:30
<2026-11-19 Thu 14:00-15:30>   from 14:00 to 15:30
[2026-09-27 Sun 18:45]         an inactive stamp with a time

In the agenda, timed entries are sorted by time and placed on the time grid; a time range shows as 14:00-15:30.

• Design review <2026-10-01 Thu 14:00-15:30>

Try: put the cursor on the 15 of 15:30 and press <C-a>.

Expect: the time part reads 14:00-16:30: the end hour moved, the start stayed.

Try: now put the cursor on the 14 and press <C-x>.

Expect: 13:00-15:30: changing the start hour moves the end along with it, so the range keeps its length. Press u twice to get back to 14:00-15:30.

Two timestamps joined by two dashes, with nothing between them, are a date range: the agenda shows the entry on every day of the range, with (1/5):, (2/5):, … in front of it.

<2026-11-23 Mon>--<2026-11-27 Fri>                 five days
<2026-11-23 Mon 09:00>--<2026-11-25 Wed 17:30>     with times at both ends
[2026-09-01 Tue]--[2026-09-15 Tue]                 inactive range (a note)

• Conference week <2026-10-05 Mon>–<2026-10-09 Fri>

Try: put the cursor inside the second timestamp (on the 09) and press <S-Right>.

Expect: the end becomes 2026-10-10 Sat, the start stays 2026-10-05 Mon: only the end you are on moves. <S-Left> brings it back.

Try: with the cursor inside the second timestamp, run :Org toggle_timestamp_type.

Expect: the second timestamp becomes [2026-10-09 Fri], the first one stays active: only that end changes. Run it again to restore it.

A repeater makes a timestamp come back. It goes after the date (and time): a mark, a number and a unit (h hours, d days, w weeks, m months, y years).

In the agenda, a repeating timestamp shows up on every occurrence (each week for +1w), not only on the next one.

<2026-12-07 Mon 09:00 +1w>       every Monday at 09:00
<2026-12-31 Thu +1y>             every year on December 31
<2026-12-01 Tue +1m>             on the 1st of every month
<2026-12-01 Tue 08:00 +2h>       every two hours
SCHEDULED: <2026-12-01 Tue .+2d/4d>   a habit: every 2 to 4 days

The /4d after a .+ repeater is the maximum interval of a habit (an entry with :STYLE: habit): see 04-todo.org and 09-agenda.org.

The last part of a timestamp, -Nd (or -Nw, -Nm, -Ny), changes when a SCHEDULED or DEADLINE entry starts showing in the agenda.

• On a DEADLINE, it is the warning period: the entry is listed on today N days before it is due, with In N d.: in front. Without one, deadline_warning_days (14) is used.
• On a SCHEDULED date, it is a delay: the entry is hidden until N days after the scheduled day.
• With a repeater, -- (two dashes) applies the period only to the first occurrence; a single - applies it to every one.
• Months and years count as 30.4 and 365.25 days.

DEADLINE: <2026-11-19 Thu -3d>        warn from Nov 16
DEADLINE: <2026-11-19 Thu -0d>        no warning at all, only on the day
DEADLINE: <2026-12-24 Thu -2w>        warn two weeks ahead
SCHEDULED: <2026-11-16 Mon -2d>       hidden until Nov 18
SCHEDULED: <2026-12-07 Mon +1w -1d>   every Monday, each shown on Tuesday
SCHEDULED: <2026-12-07 Mon +1w --1d>  only the first one delayed

SCHEDULED: and DEADLINE: go on the line right after the headline (the planning line). Both can be on the same line. CLOSED: is added there when a task is marked done (with log_done, or #+STARTUP: logdone).

* TODO Write the report
DEADLINE: <2026-11-19 Thu> SCHEDULED: <2026-11-16 Mon>

• SCHEDULED means "start working on it on that day". The entry shows up in the agenda on that day and, until it is done, on today too (Sched.Nx:, N days late).
• DEADLINE means "must be done by that day". It shows up before the day (the warning period) and keeps showing after it (N d. ago:).

Keys (on a headline or anywhere in its body):

• <prefix>s (<C-c><C-s>) asks for a date and sets SCHEDULED.
• <prefix>d (<C-c><C-d>) asks for a date and sets DEADLINE.
• On an entry that already has one, the prompt starts at that date, and the repeater, the warning and the time of the old date are kept when you don't type new ones.
• In the calendar, x (or <Del>) removes the date.
• 4<prefix>s / 4<prefix>d remove the date without a prompt.
• 16<prefix>s / 16<prefix>d ask for a second date and set the delay / warning period to the number of days between the two.
• Other counts (2<prefix>s, …) are ignored, like Emacs.
• In Visual mode, <prefix>s / <prefix>d set the date of every headline in the selection (the date prompt comes once per headline).
• A new SCHEDULED or DEADLINE date removes a CLOSED: line.

• <prefix>i. (<C-c>.) opens the calendar and inserts an active timestamp after the cursor.
• <prefix>i! (<C-c>!) does the same for an inactive one.
• With any count (4<prefix>i.), the prompt includes the current time (rounded to the first value of time_stamp_rounding_minutes; 0 = not rounded).
• With a count of 16 (16<prefix>i.), there is no prompt: the current date and time are inserted.
• With the cursor on a timestamp, the same keys change that timestamp instead of inserting a new one. The prompt starts at its date, and its repeater is kept.
• <C-c>< inserts today's date, without a prompt.
• <C-c>> opens the calendar at the date under the cursor, just to look: the date you pick is only shown as a message.

Scratch lines for the exercises:

• Call Ana
• Last haircut
• Dentist at
• Payday [2026-10-15 Thu +1m]
• Today is

Try: on "Call Ana", press $ then <prefix>i. and <CR> (accept the selected day, today).

Expect: - Call Ana followed by 2026-09-28 Mon in <>.

Try: on "Last haircut", press $ then <prefix>i!, i, type fri 14:00 and <CR>.

Expect: - Last haircut [2026-10-02 Fri 14:00].

Try: on "Dentist at", press $ then 16<prefix>i!.

Expect: - Dentist at [2026-09-28 Mon HH:MM] with the current time, and no prompt.

Try: on "Payday", put the cursor inside the timestamp and press <prefix>i!, i, type ++2d and <CR>.

Expect: - Payday [2026-10-17 Sat +1m]: the stamp was replaced, not duplicated, ++2d counted from its old date, and the +1m repeater survived.

Try: on "Today is", press $ then <C-c><.

Expect: - Today is followed by 2026-09-28 Mon in <>, without a prompt.

Every date prompt (<prefix>i., <prefix>s, <prefix>d, the agenda's date commands, capture's %^t) opens a floating calendar. It shows six weeks with ISO week numbers on the left; days of the neighbouring months are dimmed, weekends tinted, today underlined and the selected day highlighted. Below the grid: the selected date in full, the timestamp it will write, and how far it is from today ("in 3 days", "yesterday").

Keys and typing combine: if you move in the calendar and then press i, the typed text is read together with the selected date, like Emacs. So moving to next Friday and typing 14:00 gives next Friday at 14:00.

The colors are highlight groups (OrgCalendarToday, OrgCalendarSelected, …) linked to standard groups, so they follow your colorscheme; see :h org-calendar.

Scratch lines:

• Picked with the keys
• Picked with a time
• Picked by moving and typing

Try: on "Picked with the keys", press $, <prefix>i!, then l, l, j and <CR>.

Expect: [2026-10-07 Wed]: two days (Sep 30), then one week later.

Try: on "Picked with a time", press $, <prefix>i!, then L (next month), T, type 15:30, <CR> (closes the time prompt), then <CR> again to accept.

Expect: [2026-10-28 Wed 15:30].

Try: on "Picked by moving and typing", press $, <prefix>i!, then llll (Friday Oct 2), i, type 14:00 and <CR>.

Expect: [2026-10-02 Fri 14:00].

Try: press <C-c>> anywhere, move around, press q.

Expect: nothing in the buffer changes; the calendar was only for looking.

When you press i in the calendar you get a Date: prompt. It reads what you type like Emacs's org-read-date. Parts you leave out come from the default: the date being changed (an existing timestamp or SCHEDULED/DEADLINE date), or today. Text it cannot read at all is refused with the warning Cannot parse date: ... (Emacs silently uses the default date instead).

With read_date_prefer_future (on by default), a day or month typed without a year is taken in the future: on Sep 28, 15 is Oct 15 and sep 15 is next year's Sep 15.

With the cursor on a timestamp (in a paragraph, a list item, a planning line or a CLOCK line):

• <S-Right> / <S-Left> move the timestamp one day later / earlier, whatever part of it the cursor is on. A count moves by that many days.
• <S-Up> / <S-Down> (and <C-a> / <C-x>, the same thing) change the part under the cursor:
  • the year, the month, the day or the weekday name: that unit +1 / -1;
  • the hour: one hour; on a time range the end moves too;
  • the minutes: to the next multiple of 5 (the second value of time_stamp_rounding_minutes); with a count, by exactly that many minutes;
  • the end time of a range: only the end, by one hour / one minute;
  • a repeater (+1w) or warning (-3d) number: +1 / -1 (a repeater stays at least 1, a warning at least 0);
  • the unit letter of a repeater or warning: cycles d → w → m → y;
  • the bracket < or >: switch active / inactive.
• Only plain +N repeaters and -N warnings are changed, like Emacs: on ++1w, .+1d or --2d the number keys do nothing.
• The weekday name is always rewritten to match the new date.
• The cursor on the character right after a part (the -, : or space that follows it) changes that part, like point in Emacs.
• On a CLOCK line, the duration after => is recomputed (see 08-clocking.org).

When the cursor is not on a timestamp, these keys do their other jobs (TODO state and priority on headlines, bullets in lists, table cells, and Vim's own motions and number increment elsewhere).

<CR> on a timestamp (outside a link) opens the agenda day view on that date, with every entry of the agenda files for that day.

• Hackathon <2026-10-01 Thu>

Try: put the cursor on the timestamp above and press <CR>.

Expect: a day agenda Day-agenda (W40): for Thursday 1 October 2026. An entry is listed by its headline, so from this file you see, among others: 14:00-15:30 Times and time ranges (the Design review), Live examples (the Team offsite), <CR> on a date: jump to the agenda (this Hackathon) and Book club (first Thursday of each month) (a diary sexp, see below). Press q to close it.

<C-c><C-y> (Emacs org-evaluate-time-range, no <prefix> key) shows how long the range at the cursor is (or the first range on the line):

• For dates without times: whole days, e.g. 4 days.
• With times: days, hours and minutes, e.g. 2 days 8 hours 30 minutes.
• A single timestamp with a time range, [... 10:00-11:20], works too (an org.nvim extension): 1 hour 20 minutes.

With a count (4<C-c><C-y>), the result is written after the range instead: 2d 08:30, 4d or 01:20. An older result right after the range in the [Nd ]HH:MM form is replaced, so you can run it again after changing a date. (A result of whole days, like 4d, has no HH:MM part and is not recognized, so it is added again: delete the old one first. Emacs does the same.)

On a CLOCK line, <C-c><C-y> recomputes the clock duration instead.

• Holiday [2026-12-21 Mon]–[2026-12-25 Fri]
• Workshop [2026-10-05 Mon 09:00]–[2026-10-07 Wed 17:30]
• Standup [2026-10-01 Thu 10:00-11:20]

Try: on each of the three lines press <C-c><C-y>.

Expect: the messages 4 days, 2 days 8 hours 30 minutes and 1 hour 20 minutes.

Try: on "Workshop" press 4<C-c><C-y>.

Expect: the line ends in [2026-10-07 Wed 17:30] 2d 08:30 and the message is Time difference inserted.

Try: put the cursor on the 17 and press <C-a>, then 4<C-c><C-y> again.

Expect: ... [2026-10-07 Wed 18:30] 2d 09:30: the old result was replaced, not added.

Try: on "Standup" press 4<C-c><C-y>.

Expect: ... [2026-10-01 Thu 10:00-11:20] 01:20.

Durations like these (1:20, 2d 08:30, 90min) are also what clocking, efforts and column view use: see 08-clocking.org. In tables, formulas can compute with dates and times: see 16-spreadsheet.org.

The text of a timestamp is always ISO (2026-10-01 Thu), but it can be displayed differently. <C-c><C-x><C-t> (or :Org toggle_time_stamp_overlays) toggles the custom display in the buffer: each timestamp is shown with time_stamp_custom_formats, by default %m/%d/%y %a for dates and %m/%d/%y %a %H:%M for dates with a time. The file itself is not changed.

The end of a time range and a trailing repeater stay visible, like Emacs.

• Start with it on: display_custom_times = true in the setup, or #+STARTUP: customtime in a file.
• The formats are Emacs format-time-string formats, e.g. time_stamp_custom_formats = { "%A %d %B %Y", "%A %d %B %Y, %H:%M" }.
• The real text shows in Insert mode (the display uses conceal).
• While it is on, exporting the buffer writes the timestamps with the custom formats too.

• Display me [2026-10-01 Thu]
• And me [2026-10-01 Thu 10:00-11:30]
• And me too [2026-12-25 Fri]

Try: press <C-c><C-x><C-t>.

Expect: the stamps above read [10/01/26 Thu], [10/01/26 Thu 10:00-11:30] and [12/25/26 Fri] (and every other timestamp of the file changes the same way). Press i on one of the lines: the real text comes back while you are in Insert mode. <Esc>, then <C-c><C-x><C-t> again turns the display off.

For dates that are not a fixed repeat ("the first Thursday of every month", "every other Friday since Sep 4"), Org accepts Emacs diary s-expressions instead of a date:

• inside a timestamp: <%%(diary-float t 4 1)>, also after SCHEDULED: or DEADLINE:;
• or on a line of its own starting with %%(, followed by the text to show: %%(org-anniversary 2019 10 3) Wedding anniversary (%d years).

Emacs evaluates them as Emacs Lisp. org.nvim has its own emulation of the calendar functions of Emacs's diary library (diary-float, diary-block, diary-date, diary-anniversary, diary-cyclic, diary-remind, diary-offset, org-anniversary, org-block, org-cyclic, org-date, the Hebrew, Chinese, lunar and solar functions, …) plus a small, safe subset of Emacs Lisp (when, memq, and, or, arithmetic, calendar-day-of-week, …) with the same results as Emacs. Other Lisp runs in a separate emacs --batch when Emacs is installed; otherwise the entry is skipped with a message. The full list is in :h org-agenda-diary-sexp.

• Diary sexps only matter to the agenda: the date keys of this file (<S-Right>, <C-a>, the prompt) don't edit them.
• Argument order: the diary-* functions follow agenda.calendar_date_style, American by default (MONTH DAY YEAR); the org-* functions always take YEAR MONTH DAY.
• In diary-float, the day of the week is 0 (Sunday) to 6, t means any month, and a negative N counts from the end of the month.

• :h org-dates: timestamps, the insertion and editing keys, the custom display.
• :h org-calendar: the calendar popup and its highlight groups.
• :h org-read-date: the date input language.
• :h org-repeat: repeated tasks; :h org-todo-events for logging.
• :h org-agenda-diary-sexp: every supported diary function.
• :h org-durations: durations and their formats.
• :h org-config: deadline_warning_days, read_date_prefer_future, time_stamp_rounding_minutes, display_custom_times, time_stamp_custom_formats, extend_today_until, log_reschedule.
• The other example files: 04-todo.org (repeating tasks and habits), 08-clocking.org (clocking), 09-agenda.org (the agenda) and 20-timers-reminders.org (reminders for timed entries).