Clocking time with Org-mode

Org-mode is pretty large, there is a lot of things you can do with it. Check out the previous meetup about it. This assumes you've using Org-mode at least a little bit (headlines and TODOs) before.

I'd like to thank Bernt Hansen, whose org-mode configuration I have heavily borrowed and tweaked to make my own.

So, you want to track time in tasks in Org-mode? First, you need a task, any headline can be clocked in to. In order to clock in to a task, hit C-c C-x C-i, and hit C-c C-x C-o to clock back out.

When you clock in to a headline a drawer appears, a drawer looks like this:

You can expand and collapse the drawer with TAB. Time tracking goes into the :LOGBOOK: drawer (you might have already seen the :PROPERTIES: drawer) and looks like:

:LOGBOOK:
CLOCK: [2017-04-10 Mon 15:18]
CLOCK: [2017-04-10 Mon 15:16]--[2017-04-10 Mon 15:17] =>  0:01
CLOCK: [2017-04-07 Fri 16:05]--[2017-04-07 Fri 16:35] =>  0:30
CLOCK: [2017-04-05 Wed 16:42]--[2017-04-05 Wed 16:52] =>  0:10
:END:

(the first one is a currently open clock)

That's it! Keep clocking away and capturing where your time went. You will also see a notification in the modeline with your current task and how long it's been going for.

For a quick overview C-c C-x C-d provides a quick summary of clocked time for the current org file.

C-c C-x C-r starts generating a new clock report/table, or you can manually add this line to a file and hit C-c C-c on it:

#+BEGIN: clocktable
#+END:

And then you can put options on the BEGIN line:

#+BEGIN: clocktable :maxlevel 4 :scope agenda :block thismonth
#+END:

Here's a large example (I left a lot out for sensitivity):

You can change the default clocktable options with:

;; Agenda clock report parameters
(setq org-agenda-clockreport-parameter-plist
      '(:link t :maxlevel 6 :fileskip0 t :compact t :narrow 60 :score 0))

My agenda org clock report settings show 6 levels of detail with links to the tasks. I like wider reports than the default compact setting so I override the :narrow value.

Want to see a clock table in the Agenda? Simply press v R to show it, then hit v R again to turn it off.

Sometimes you need to manually make changes to a clock, because it's wrong, or you forgot to clock in, or your cat jumped on to your keyboard and clocked in to an embarrassing task.

Okay, you can clock in to tasks and generate reports, but what about estimating the amount of time a task will take, and seeing how well you line up in actual time?

Well, you can hit C-c C-x e to be prompted to set the "effort" for a particular headline, which will go into the :PROPERTIES: drawer. Something like "30" for 30 minutes, or "1:30" for an hour and a half. Now when you clock in to a task, instead of seeing [1:04] Do some stuff you'll see [1:04/2:00] Do some stuff where the effort is displayed next to the clock time.

A speedier way of doing this though, is to have some "presets" that you can easily hotkey for effort, you can add these to org-global-properties:

;; global Effort estimate values
(setq org-global-properties
      '(("Effort_ALL" .
         "0:15 0:30 0:45 1:00 2:00 3:00 4:00 5:00 6:00 0:00")))
;;        1    2    3    4    5    6    7    8    9    0
;; These are the hotkeys ^^

Then, you can hit C-c C-x e on a headline and be prompted for the "quick" efforts. So C-c C-x e 3 would select 45 minutes.

Cool, so you estimated (poorly, remember, we are in software, no good estimates allowed!) the time for all your tasks now to compare. For comparing, we're going to use Org-modes column view mode.

We need to define some columns to see, I like to define mine as the task, then the priority, the effort, and finally the sum of time taken for the task:

;; Set default column view headings: Task Priority Effort Clock_Summary
(setq org-columns-default-format "%50ITEM(Task) %2PRIORITY %10Effort(Effort){:} %10CLOCKSUM")

You can now turn on org-columns with C-c C-x C-c, you should see something like the following screenshots.¹

Before:

After:

You can move to the "Effort" column and hit 0-9 to fast-choose the amount of effort for a task also, instead of adding effort to each individual headline one at a time.

You can exit org-columns view by hitting q

Or, generate a local column view with C-c C-x i (select "local" to see the local column table).

I like to have a helpful history of tasks to pick from when I clock in to things. Which is what this does. I bind it to C-c I and C-c O so they can be invoked globally (not just in org-mode files).

;; Show lot of clocking history so it's easy to pick items off the `C-c I` list
(setq org-clock-history-length 23)

(defun eos/org-clock-in ()
  (interactive)
  (org-clock-in '(4)))

(global-set-key (kbd "C-c I") #'eos/org-clock-in)
(global-set-key (kbd "C-c O") #'org-clock-out)

Sometimes you may want to resume the clock that was running when Emacs was stopped, you can make org do that with these settings:

;; Resume clocking task when emacs is restarted
(org-clock-persistence-insinuate)
;; Save the running clock and all clock history when exiting Emacs, load it on startup
(setq org-clock-persist t)
;; Resume clocking task on clock-in if the clock is open
(setq org-clock-in-resume t)
;; Do not prompt to resume an active clock, just resume it
(setq org-clock-persist-query-resume nil)

And here are a few other settings you might want to check out:

;; Change tasks to whatever when clocking in
(setq org-clock-in-switch-to-state "NEXT")
;; Save clock data and state changes and notes in the LOGBOOK drawer
(setq org-clock-into-drawer t)
;; Sometimes I change tasks I'm clocking quickly - this removes clocked tasks
;; with 0:00 duration
(setq org-clock-out-remove-zero-time-clocks t)
;; Clock out when moving task to a done state
(setq org-clock-out-when-done t)
;; Enable auto clock resolution for finding open clocks
(setq org-clock-auto-clock-resolution (quote when-no-clock-is-running))
;; Include current clocking task in clock reports
(setq org-clock-report-include-clocking-task t)
;; use pretty things for the clocktable
(setq org-pretty-entities t)