8.4 Clocking work time

Org mode allows you to clock the time you spend 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. And it remembers a history or tasks recently clocked, to that you can jump quickly between a number of tasks absorbing your time.

To save the clock history across Emacs sessions, use

     (setq org-clock-persist 'history)
     (org-clock-persistence-insinuate)

When you clock into a new task after resuming Emacs, the incomplete clock¹ will be found (see Resolving idle time) and you will be prompted about what to do with it.

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 :LOGBOOK: 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.
While the clock is running, the current clocking time is shown in the mode line, along with the title of the task. The clock time shown will be all time ever clocked for this task and its children. If the task has an effort estimate (see Effort estimates), the mode line displays the current clocking time against it² If the task is a repeating one (see Repeated tasks), only the time since the last reset of the task ³ will be shown. More control over what time is shown can be exercised with the CLOCK_MODELINE_TOTAL property. It may have the values current to show only the current clocking instance, today to show all time clocked on this tasks today (see also the variable org-extend-today-until), all to include all time, or auto which is the default⁴.
Clicking with mouse-1 onto the mode line entry will pop up a menu with clocking options.

C-c C-x C-o

Stop the clock (clock-out). This 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 timestamp⁵.

C-c C-x C-e

Update the effort estimate for the current clock task.

C-c C-y or C-c C-c

Recompute the time interval after changing one of the timestamps. This is only necessary if you edit the timestamps 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.
          :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.
          :timestamp   A timestamp for the entry, when available.  Look for SCHEDULED,
                       DEADLINE, TIMESTAMP and TIMESTAMP_IA, in this order.

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

A summary of the current subtree with % times would be

          #+BEGIN: clocktable :scope subtree :link t :formula %
          #+END: clocktable

C-c C-c

C-c C-x C-u

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>

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.