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 compatible1 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 thenm
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.
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.