Next: , Previous: , Up: Clocking Work Time   [Contents][Index]


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:

nilthe current buffer or narrowed region
filethe full current buffer
subtreethe subtree where the clocktable is located
treeNthe surrounding level N tree, for example ‘tree3
treethe surrounding level 1 tree
agendaall agenda files
("file" ...)scan these files
FUNCTIONscan files returned by calling FUNCTION with no argument
file-with-archivescurrent file and its archives
agenda-with-archivesall 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-31New year eve 2007
2007-12December 2007
2007-W50ISO-week 50 in 2007
2007-Q22nd quarter in 2007
2007the year 2007
today’, ‘yesterday’, ‘today-Na relative day
thisweek’, ‘lastweek’, ‘thisweek-Na relative week
thismonth’, ‘lastmonth’, ‘thismonth-Na relative month
thisyear’, ‘lastyear’, ‘thisyear-Na relative year
untilnow78all 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

Language79 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 write80

#+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

Footnotes

(78)

When using :step, untilnow starts from the beginning of 2003, not the beginning of time.

(79)

Language terms can be set through the variable org-clock-clocktable-language-setup.

(80)

Note that all parameters must be specified in a single line—the line is broken here only to fit it into the manual.


Next: , Previous: , Up: Clocking Work Time   [Contents][Index]