Next: Resolving idle time, Previous: Clocking commands, 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: Resolving idle time, Previous: Clocking commands, Up: Clocking work time [Contents][Index]