- publishing free software manuals
The Org Mode 7 Reference Manual
by Carsten Dominik and others
Paperback (6"x9"), 282 pages
ISBN 9781906966089
RRP £9.95 ($14.95)

Sales of this book support the Org project! Get a printed copy>>>

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)

When you clock into a new task after resuming Emacs, the incomplete clock(61) will be found (see section 8.5 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 section 8.6 Effort estimates), the mode line displays the current clocking time against it(62) If the task is a repeating one (see section 8.3.2 Repeated tasks), only the time since the last reset of the task (63) 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.(64)
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.(65)
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 headline of the currently clocked in task. 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 section 16.16 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:
Maximum level depth to which times are listed in the table.
When t, emphasize level one and level two items.
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
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.
A time string specifying when to start considering times.
A time string specifying when to stop considering times.
week or day, to split the table into chunks. To use this, :block or :tstart, :tend are needed.
Don't show steps that have zero time
A tags match to select entries that should contribute
Link the item headlines in the table to their origins.
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.
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(66)
#+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 section 16.16 Dynamic blocks). This is useful if you have several clock table blocks in a buffer.
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 section 10.3.4 Timeline for a single file) and in the agenda (see section 10.3.1 The weekly/daily agenda) to show which tasks have been worked on or closed during a day.

ISBN 9781906966089The Org Mode 7 Reference ManualSee the print edition