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.

C-c C-x C-r     (org-clock-report)

Insert a dynamic block (see 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 (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. 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(85) 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 write86 

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

(85)

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

(86)

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]