Klog and Emacs Diary

The todo-based time tracking facility Org Mode provides does not suit well my workflow. When I archive todo entries the time tracking reporting structure is lost and very often I have activities which do not nicely fit a specific todo.

While looking for an alternative text-based time tracking solution, I stumbled upon Klog and I fell in love with the text format it uses and the app.

This post includes a couple of notes about Klog and, more important, how I integrated it in my Emacs workflow.

Klog

Klog is a time tracking solution which uses a diary-like plain-text format for storing entries. Entries look like this:

2024-07-13
Writing about Klog
   10:00-11:00 #writing about Klog
   8h relaxing

Days are written in the ISO format, tags allow to mark important keywords, an initial description can be used to describe the day, overall. No need to specify a specific time for some entries, which I really appreciate, since other tools often require to specify a specific time in order to enter time tracking entries and, when I catch-up with old entries, I have a good idea of the time spent, but the actual start and end times of each specific activity are just guess work.

You can then generate reports with the following command:

klog report --tag=work,time_tracking --aggregate=month --this-month

See the Klog documentation for more details.

Klog and Emacs

On top of being very easy to read and parse I find remarkable that the Klog format is mostly compatible¹ with that of Emacs diary mode and, more specifically, the fancy display format.

It is therefore possible to setup Emacs to display and enter new Klog entries, simply by setting up a few variables, in fact, making Emacs a rather cool editor for managing Klog entries.

More specifically, we just need to:

Specify that the Klog file is our diary file
Specify that we use the fancy diary display and the ISO format for dates

That is:

;;;
;;; Alternatively, you can use #include and the hooks below
;;;
(setq diary-file (expand-file-name "~adolfo/TimeTrack/2024.klg"))

(setq calendar-mark-diary-entries t)
(setq calendar-date-style 'iso)
(setq diary-date-forms diary-iso-date-forms)
(setq calendar-date-display-form calendar-iso-date-display-form)
(setq diary-display-function 'diary-fancy-display)

;;;
;;; these are useful if you prefer to include time tracking entries
;;; in the diary
;;;
(add-hook 'diary-list-entries-hook 'diary-include-other-diary-files)
(add-hook 'diary-mark-entries-hook 'diary-mark-included-diary-files)
(add-hook 'diary-list-entries-hook 'diary-sort-entries)

;;;
;;; These are not necessary
;;;
(setq diary-list-include-blanks t)
(setq cal-html-directory (expand-file-name "~adolfo/public_html"))
(setq cal-html-print-day-number-flag t)

With the setup above (which maybe can be simplified a bit), we can now use Emacs’ diary commands to view a manipulate Klog files.

For instance:

M-x calendar and then m will show a three-month calendar and mark the days where there are time tracking entries
The key sequence i d will open the Klog file and allow to add an entry for the current day.
s d will show the time tracking entries for the current day.

Emacs showing Klog Enties

Klog, Emacs Diary, and Org Mode

If you prefer to view the entries in the Org Mode agenda, just add the following to your .emacs file:
```
(setq org-agenda-include-diary t)
```
This opens up a bunch of additional features, among which the possibility of exporting the agenda, ahem, time tracking entries, in different formats, including iCalendar, HTML and Postscript.

Footnotes:

The Emacs diary does not understand Klog’s summary line, which will most likely break the entries for a given day. Moreover, Emacs diary will not understand Klog’s number of expected hours, even though I believe we can set calendar-date-style and diary-date-forms diary-iso-date-forms to make it work. All the rest should be fine: entries with time clocked and no timestamps, for instance, should be interpreted as full-day entries. Moreover, since the Emacs diary works even with files with errors, these incompatibilities should not constitute a big problem, unless you use them systematically.