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.

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—h, d, w, m or y—to indicate a change in hours, days, weeks, months, or years. With h the date is relative to the current time, with the other letters and a single plus or minus, the date is relative to today at 00:00. 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.:

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.:

Parallel to the minibuffer prompt, a calendar is popped up(note: If you do not need/want the calendar, configure the variable org-popup-calendar-for-date-prompt.). 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:

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(note: If you find this distracting, turn off the display with org-read-date-display-live.).

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 variables org-display-custom-times and org-timestamp-custom-formats.

C-c C-x C-t (org-toggle-timestamp-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 point onto a timestamp anymore, only before or after.
• The S-UP and S-DOWN keys can no longer be used to adjust each component of a timestamp. If point is at the beginning of the stamp, S-UP and S-DOWN change the stamp by one day, just like S-LEFT S-RIGHT. At the end of the stamp, change the time by one minute.
• If the timestamp contains a range of clock times or a repeater, these are not overlaid, but remain in the buffer as they were.
• When you delete a timestamp character-by-character, it only disappears from the buffer after all (invisible) characters belonging to the ISO timestamp have been removed.
• 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.

The following commands allow you to quickly insert a deadline or to

schedule an item:²⁴

C-c C-d (org-deadline)

Insert DEADLINE keyword along with a stamp. The insertion happens in the line directly following the headline. Remove any CLOSED timestamp . When called with a prefix argument, also remove any existing deadline from the entry. Depending on the variable org-log-redeadline, take a note when changing an existing deadline(note: Note the corresponding STARTUP options logredeadline, lognoteredeadline, and nologredeadline.).

C-c C-s (org-schedule)

Insert SCHEDULED keyword along with a stamp. The insertion happens in the line directly following the headline. Remove any CLOSED timestamp. When called with a prefix argument, also remove the scheduling date from the entry. Depending on the variable org-log-reschedule, take a note when changing an existing scheduling time(note: Note the corresponding STARTUP options logreschedule, lognotereschedule, and nologreschedule.).

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. With a 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 sets the date to the next day after today, and --1w sets the date to the previous week before any current timestamp.

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 timestamps²⁵. 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, m, w, d and 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 done once you have done so. When you mark a DEADLINE or a SCHEDULED with the TODO keyword DONE, it no longer produces entries in the agenda. The problem with this is, however, is 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 as done, using C-c C-t, it shifts the base date of the repeating timestamp by the repeater interval, and immediately sets the entry state back to TODO(note: In fact, the target state is taken from, in this sequence, the REPEAT_TO_STATE property, the variable org-todo-repeat-to-state if it is a string, the previous TODO state if org-todo-repeat-to-state is t, or the first state of the TODO state sequence.). 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>

When task contains multiple timestamps with repeater interval, all these timestamps are shifted.

To mark a task with a repeater as DONE, use C-- 1 C-c C-t, i.e., org-todo with a numeric prefix argument of -1.

A timestamp²⁶ is added under the deadline, to keep a record that you actually acted on the previous instance of this deadline.

As a consequence of shifting the base date, this entry is no longer visible in the agenda when checking past dates, but all future instances will be visible.

With the +1m cookie, the date shift is always exactly one month. So if you have not paid the rent for three months, marking this entry DONE still keeps it as an overdue deadline. Depending on the task, this may not be the best way to handle it. For example, if you forgot to call your father for 3 weeks, it does not make sense to call him 3 times in a single day to make up for it. Finally, there are tasks, like changing batteries, which should always repeat a certain time after the last time you did it. For these tasks, Org mode has special repeaters ++ and .+. For example:

** TODO Call Father
   DEADLINE: <2008-02-10 Sun ++1w>
   Marking this DONE shifts the date by at least one week, but also
   by as many weeks as it takes to get this date into the future.
   However, it stays on a Sunday, even if you called and marked it
   done on Saturday.

** TODO Empty kitchen trash
   DEADLINE: <2008-02-08 Fri 20:00 ++1d>
   Marking this DONE shifts the date by at least one day, and also
   by as many days as it takes to get the timestamp into the future.
   Since there is a time in the timestamp, the next deadline in the
   future will be on today's date if you complete the task before
   20:00.

** TODO Check the batteries in the smoke detectors
   DEADLINE: <2005-11-01 Tue .+1m>
   Marking this DONE shifts the date to one month after today.

** TODO Wash my hands
   DEADLINE: <2019-04-05 08:00 Fri .+1h>
   Marking this DONE shifts the date to exactly one hour from now.

You may have both scheduling and deadline information for a specific task. If the repeater is set for the scheduling information only, you probably want the repeater to be ignored after the deadline. If so, set the variable org-agenda-skip-scheduled-repeats-after-deadline to t. However, any scheduling information without a repeater is no longer relevant once the task is done, and thus, removed upon repeating the task. If you want both scheduling and deadline information to repeat after the same interval, set the same repeater for both timestamps.

An alternative to using a repeater is to create a number of copies of a task subtree, with dates shifted in each copy. The command C-c C-x c was created for this purpose; it is described in Structure Editing.

C-c C-x C-i (org-clock-in)

Start the clock on the current item (clock-in). This inserts the CLOCK keyword together with a timestamp. If this is not the first clocking of this item, the multiple CLOCK lines are wrapped into a LOGBOOK drawer (see also the variable org-clock-into-drawer). You can also overrule the setting of this variable for a subtree by setting a CLOCK_INTO_DRAWER or LOG_INTO_DRAWER property. When called with a C-u prefix argument, select the task from a list of recently clocked tasks. With two C-u C-u prefixes, clock into the task at point and mark it as the default task; the default task is always be available with letter d when selecting a clocking task. With three C-u C-u C-u prefixes, force continuous clocking by starting the clock when the last clock stopped.

While the clock is running, Org shows the current clocking time in the mode line, along with the title of the task. The clock time shown is all time ever clocked for this task and its children. If the task has an effort estimate (see Effort Estimates), the mode line displays the current clocking time against it(note: To add an effort estimate "on the fly", hook a function doing this to org-clock-in-prepare-hook.). If the task is a repeating one (see Repeated tasks), show only the time since the last reset of the task(note: The last reset of the task is recorded by the LAST_REPEAT property.). You can exercise more control over show time with the CLOCK_MODELINE_TOTAL property. It may have the values current to show only the current clocking instance, today to show all time clocked on this tasks today—see also the variable org-extend-today-until, all to include all time, or auto which is the default(note: See also the variable org-clock-mode-line-total.). Clicking with mouse-1 onto the mode line entry pops up a menu with clocking options.

C-c C-x C-o (org-clock-out)

Stop the clock (clock-out). This inserts another timestamp at the same location where the clock was last started. It also directly computes the resulting time in inserts it after the time range as =>HH:MM. See the variable org-log-note-clock-out for the possibility to record an additional note together with the clock-out timestamp(note: The corresponding in-buffer setting is: #+STARTUP: lognoteclock-out.).

C-c C-x C-x (org-clock-in-last)

Re-clock the last clocked task. With one C-u prefix argument, select the task from the clock history. With two C-u prefixes, force continuous clocking by starting the clock when the last clock stopped.

C-c C-x C-e (org-clock-modify-effort-estimate)

Update the effort estimate for the current clock task.

C-c C-c or C-c C-y (org-evaluate-time-range)

Recompute the time interval after changing one of the timestamps. This is only necessary if you edit the timestamps directly. If you change them with S-<cursor> keys, the update is automatic.

C-S-UP (org-clock-timestamps-up), C-S-DOWN (org-clock-timestamps-down)

On CLOCK log lines, increase/decrease both timestamps so that the clock duration keeps the same value.

S-M-UP (org-timestamp-up), S-M-DOWN (org-timestamp-down)

On CLOCK log lines, increase/decrease the timestamp at point and the one of the previous, or the next, clock timestamp by the same duration. For example, if you hit S-M-UP to increase a clocked-out timestamp by five minutes, then the clocked-in timestamp of the next clock is increased by five minutes.

Only CLOCK logs created during current Emacs session are considered when adjusting next/previous timestamp.

C-c C-t (org-todo)

Changing the TODO state of an item to DONE automatically stops the clock if it is running in this same item.

C-c C-x C-q (org-clock-cancel)

Cancel the current clock. This is useful if a clock was started by mistake, or if you ended up working on something else.

C-c C-x C-j (org-clock-goto)

Jump to the headline of the currently clocked in task. With a C-u prefix argument, select the target task from a list of recently clocked tasks.

C-c C-x C-d (org-clock-display)

Display time summaries for each subtree in the current buffer. This puts overlays at the end of each headline, showing the total time recorded under that heading, including the time of any subheadings. You can use visibility cycling to study the tree, but the overlays disappear when you change the buffer (see variable org-remove-highlights-with-change) or press C-c C-c.

The l key may be used in the agenda (see Weekly/daily agenda) to show which tasks have been worked on or closed during a day.

Important: note that both org-clock-out and org-clock-in-last can have a global keybinding and do not modify the window disposition.

Org mode can produce quite complex reports based on the time clocking information. Such a report is called a clock table, because it is formatted as one or several Org tables.

org-clock-report

Insert or update a clock table. When called with a prefix argument, jump to the first clock table in the current document and update it. The clock table includes archived trees.

This command can be invoked by calling org-dynamic-block-insert-dblock (C-c C-x x) and selecting "clocktable" (see Dynamic Blocks).

C-c C-c or C-c C-x C-u (org-dblock-update)

Update dynamic block at point. Point needs to be in the BEGIN line of the dynamic block.

C-u C-c C-x C-u

Update all dynamic blocks (see Dynamic Blocks). This is useful if you have several clock table blocks in a buffer.

S-LEFT, S-RIGHT (org-clocktable-try-shift)

Shift the current :block interval and update the table. Point needs to be in the #+BEGIN: clocktable line for this command. If :block is today, it is shifted to today-1, etc.

Here is an example of the frame for a clock table as it is inserted into the buffer by org-clock-report:

#+BEGIN: clocktable :maxlevel 2 :emphasize nil :scope file
#+END:

The #+BEGIN line contains options to define the scope, structure, and formatting of the report. Defaults for all these options can be configured in the variable org-clocktable-defaults.

First there are options that determine which clock entries are to be selected:

:maxlevel

Maximum level depth to which times are listed in the table. Clocks at deeper levels are summed into the upper level.

:scope

The scope to consider. This can be any of the following:

nil	the current buffer or narrowed region
file	the full current buffer
subtree	the subtree where the clocktable is located
treeN	the surrounding level N tree, for example tree3
tree	the surrounding level 1 tree
agenda	all agenda files
("file" ...)	scan these files
FUNCTION	scan files returned by calling FUNCTION with no argument
file-with-archives	current file and its archives
agenda-with-archives	all agenda files, including archives

:block

The time block to consider. This block is specified either absolutely, or relative to the current time and may be any of these formats:

2007-12-31	New year eve 2007
2007-12	December 2007
2007-W50	ISO-week 50 in 2007
2007-Q2	2nd quarter in 2007
2007	the year 2007
today, yesterday, today-N	a relative day
thisweek, lastweek, thisweek-N	a relative week
thismonth, lastmonth, thismonth-N	a relative month
thisyear, lastyear, thisyear-N	a relative year

When this option is not set, Org falls back to the value in org-clock-display-default-range, which defaults to the current year.

Use S-LEFT or S-RIGHT to shift the time interval.

:tstart

A time string specifying when to start considering times. Relative times like "<-2w>" can also be used. See Matching tags and properties for relative time syntax.

:tend

A time string specifying when to stop considering times. Relative times like "<now>" can also be used. See Matching tags and properties for relative time syntax.

:wstart

The starting day of the week. The default is 1 for Monday.

:mstart

The starting day of the month. The default is 1 for the first.

:step

Set to day, week, semimonth, month, quarter, or year to split the table into chunks. To use this, either :block, or :tstart and :tend are required.

:stepskip0

When non-nil, do not show steps that have zero time.

:fileskip0

When non-nil, do not show table sections from files which did not contribute.

:match

A tags match to select entries that should contribute. See Matching tags and properties for the match syntax.

Then there are options that determine the formatting of the table. There options are interpreted by the function org-clocktable-write-default, but you can specify your own function using the :formatter parameter.

:emphasize

When non-nil, emphasize level one and level two items.

:lang

Language(note: Language terms can be set through the variable org-clock-clocktable-language-setup.) to use for descriptive cells like "Task".

:link

Link the item headlines in the table to their origins.

:narrow

An integer to limit the width of the headline column in the Org table. If you write it like 50!, then the headline is also shortened in export.

:indent

Indent each headline field according to its level.

:filetitle

Show title in the file column if the file has a #+title.

:hidefiles

Hide the file column when multiple files are used to produce the table.

:tcolumns

Number of columns to be used for times. If this is smaller than :maxlevel, lower levels are lumped into one column.

:level

Should a level number column be included?

:sort

A cons cell containing the column to sort and a sorting type. E.g., :sort (1 . ?a) sorts the first column alphabetically.

:compact

Abbreviation for :level nil :indent t :narrow 40! :tcolumns 1. All are overwritten except if there is an explicit :narrow.

:timestamp

A timestamp for the entry, when available. Look for SCHEDULED, DEADLINE, TIMESTAMP and TIMESTAMP_IA special properties (see Special Properties), in this order.

:tags

When this flag is non-nil, show the headline's tags.

:properties

List of properties shown in the table. Each property gets its own column.

:inherit-props

When this flag is non-nil, the values for :properties are inherited.

:formula

Content of a TBLFM keyword to be added and evaluated. As a special case, :formula % adds a column with % time. If you do not specify a formula here, any existing formula below the clock table survives updates and is evaluated.

:formatter

A function to format clock data and insert it into the buffer.

To get a clock summary of the current level 1 tree, for the current day, you could write:

#+BEGIN: clocktable :maxlevel 2 :block today :scope tree1 :link t
#+END:

To use a specific time range you could write(note: Note that all parameters must be specified in a single line—the line is broken here only to fit it into the manual.)

#+BEGIN: clocktable :tstart "<2006-08-10 Thu 10:00>"
                    :tend "<2006-08-10 Thu 12:00>"
#+END:

A range starting a week ago and ending right now could be written as

#+BEGIN: clocktable :tstart "<-1w>" :tend "<now>"
#+END:

A summary of the current subtree with % times would be

#+BEGIN: clocktable :scope subtree :link t :formula %
#+END:

A horizontally compact representation of everything clocked during last week would be

#+BEGIN: clocktable :scope agenda :block lastweek :compact t
#+END: