8.4.2 The clock table

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

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
‘untilnow’78	all clocked time ever

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’, 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⁷⁹ 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.

‘: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: clocktable

To use a specific time range you could write⁸⁰

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

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

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

A summary of the current subtree with % times would be

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

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

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