Next: Resolving idle time, Previous: Clocking commands, Up: Clocking work time

#### 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.
`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.
         :tend        A time string specifying when to stop considering times.
         :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.

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.
         :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.
         :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 write1

         #+BEGIN: clocktable :tstart "<2006-08-10 Thu 10:00>"
                             :tend "<2006-08-10 Thu 12:00>"
         #+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] Note that all parameters must be specified in a single line—the line is broken here only to fit it into the manual.