org: The clock table
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.
‘C-c C-x C-r (org-clock-report)’
Insert a dynamic block (
Dynamic blocks) containing a clock
report as an Org mode table into the current file. When the cursor
is at an existing clock table, just update it. When called with a
prefix argument, jump to the first clock report in the current
document and update it. The clock table always includes also trees
with ‘:ARCHIVE:’ tag.
‘C-c C-c or C-c C-x C-u (org-dblock-update)’
Update dynamic block at point. The cursor needs to be in the
‘#+BEGIN’ line of the dynamic block.
‘C-u C-c C-x C-u’
Update all dynamic blocks (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. The
cursor needs to be in the ‘#+BEGIN: clocktable’ line for this
command. If ‘:block’ is ‘today’, it will be shifted to ‘today-1’
etc.
Here is an example of the frame for a clock table as it is inserted
into the buffer with the ‘C-c C-x C-r’ command:
#+BEGIN: clocktable :maxlevel 2 :emphasize nil :scope file
#+END: clocktable
The ‘BEGIN’ line and specify a number of 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 will be 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
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
absolute, 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
Use ‘S-<left>/<right>’ keys 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 1 is for the first
day of the month.
:step ‘week’ or ‘day’, to split the table into chunks.
To use this, ‘:block’ or ‘:tstart’, ‘:tend’ are needed.
:stepskip0 Do not show steps that have zero time.
:fileskip0 Do not show table sections from files which did not contribute.
:tags A tags match to select entries that should contribute. See
Matching tags and properties for the match syntax.
Then there are options which 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 ‘t’, emphasize level one and level two items.
:lang Language(1) 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 will also be shortened in export.
:indent Indent each headline field according to its level.
:tcolumns Number of columns to be used for times. If this is smaller
than ‘:maxlevel’, lower levels will be lumped into one column.
:level Should a level number column be included?
: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, in this order.
:properties List of properties that should be shown in the table. Each
property will get its own column.
:inherit-props When this flag is ‘t’, the values for ‘:properties’ will be inherited.
:formula Content of a ‘#+TBLFM’ line 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 will survive updates and be 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
and to use a specific time range you could write(2)
#+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 ----------
(1) Language terms can be set through the variable
‘org-clock-clocktable-language-setup’.
(2) Note that all parameters must be specified in a single line—the
line is broken here only to fit it into the manual.
Info Catalog
org: Clocking commands
org: Clocking work time
org: Resolving idle time