Next: Resolving idle time, Previous: Clocking commands, Up: Clocking work time [Contents][Index]
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 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.
org-dblock-update)Update dynamic block at point. The cursor needs to be in the
#+BEGIN line of the dynamic block.
Update all dynamic blocks (see Dynamic blocks). This is useful if you have several clock table blocks in a buffer.
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 exampletree3tree 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. :stepweekorday, to split the table into chunks. To use this,:blockor:tstart,:tendare 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 Whent, 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 1All 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 ist, the values for:propertieswill be inherited. :formula Content of a#+TBLFMline 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
Language terms can be set through the variable org-clock-clocktable-language-setup.
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]