8.4 Clocking work time

Org mode allows you to clock the time you spent on specific tasks in a project. When you start working on an item, you can start the clock. When you stop working on that task, or when you mark the task done, the clock is stopped and the corresponding time interval is recorded. It also computes the total time spent on each subtree of a project.

C-c C-x C-i

Start the clock on the current item (clock-in). This inserts the CLOCK keyword together with a timestamp. If this is not the first clocking of this item, the multiple CLOCK lines will be wrapped into a :CLOCK: drawer (see also the variable org-clock-into-drawer). When called with a C-u prefix argument, select the task from a list of recently clocked tasks. With two C-u C-u prefixes, clock into the task at point and mark it as the default task. The default task will always be available when selecting a clocking task, with letter d.

C-c C-x C-o

Stop the clock (clock-out). The inserts another timestamp at the same location where the clock was last started. It also directly computes the resulting time in inserts it after the time range as `=> HH:MM'. See the variable org-log-note-clock-out for the possibility to record an additional note together with the clock-out time stamp¹.

C-c C-y

Recompute the time interval after changing one of the time stamps. This is only necessary if you edit the time stamps directly. If you change them with S-<cursor> keys, the update is automatic.

C-c C-t

Changing the TODO state of an item to DONE automatically stops the clock if it is running in this same item.

C-c C-x C-x

Cancel the current clock. This is useful if a clock was started by mistake, or if you ended up working on something else.

C-c C-x C-j

Jump to the entry that contains the currently running clock. With a C-u prefix arg, select the target task from a list of recently clocked tasks.

C-c C-x C-d

Display time summaries for each subtree in the current buffer. This puts overlays at the end of each headline, showing the total time recorded under that heading, including the time of any subheadings. You can use visibility cycling to study the tree, but the overlays disappear when you change the buffer (see variable org-remove-highlights-with-change) or press C-c C-c.

C-c C-x C-r

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.

          #+BEGIN: clocktable :maxlevel 2 :emphasize nil :scope file
          #+END: clocktable
     

If such a block already exists at point, its content is replaced by the new table. The `BEGIN' line can specify options:

          :maxlevel    Maximum level depth to which times are listed in the table.
          :emphasize   When t, emphasize level one and level two items
          :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          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.
          :link        Link the item headlines in the table to their origins
     

So 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²

          #+BEGIN: clocktable :tstart "<2006-08-10 Thu 10:00>"
                              :tend "<2006-08-10 Thu 12:00>"
          #+END: clocktable
     

C-c C-c

C-c C-x C-u

Update dynamical 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>

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.

The l key may be used in the timeline (see Timeline) and in the agenda (see Weekly/daily agenda) to show which tasks have been worked on or closed during a day.