|The Org Mode 7 Reference Manual
by Carsten Dominik and others
Paperback (6"x9"), 282 pages
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) (org-clock-persistence-insinuate)
- 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_TOTALproperty. It may have the values
currentto show only the current clocking instance,
todayto show all time clocked on this tasks today (see also the variable
allto include all time, or
autowhich 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-outfor 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
#+BEGIN: clocktable :maxlevel 2 :emphasize nil :scope file #+END: clocktableIf 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.
t, emphasize level one and level two items.
The scope to consider. This can be any of the following:
the current buffer or narrowed region
the full current buffer
the subtree where the clocktable is located
the surrounding level N tree, for example
the surrounding level 1 tree
all agenda files
scan these files
current file and its 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
New year eve 2007
ISO-week 50 in 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
- A time string specifying when to start considering times.
- A time string specifying when to stop considering times.
day, to split the table into chunks. To use this,
- 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
#+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.
- A timestamp for the entry, when available. Look for SCHEDULED, DEADLINE, TIMESTAMP and TIMESTAMP_IA, in this order.
#+BEGIN: clocktable :maxlevel 2 :block today :scope tree1 :link t #+END: clocktableand 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: clocktableA 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
#+BEGINline 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
:blockinterval and update the table. The cursor needs to be in the
#+BEGIN: clocktableline for this command. If
today, it will be shifted to
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 9781906966089||The Org Mode 7 Reference Manual||See the print edition|