Time Tracking in Emacs

Joseph Brenner

June 10, 2009

What do you do if you're working on multiple projects and you need to track how much time you've spent on each? There's an emacs package called timeclock.el (standard in Gnu emacs now) that almost works, but it's biased toward the idea that you have a single employer (and that you're trying to work a regular 8 hour day, which seems even weirder for a programmer).

So I turned to the timeclock-x.el package which improves things slightly, but it, too, has some missing pieces...

At that point I stopped looking at other people's code, and wrote some of my own: a perl script that crunches the time log to do summary reports, and an elisp wrapper to run the script... This page is a write-up to explain how I do these things.

The main virtue of my approach (without having evaluated all of the competition) is that this is a relatively flexible, stand-alone, way of doing these things. You can invent new "project" names any time you choose to clock-in...

getting started

Download these and install them to somwhere in your emacs load-path:

timeclock-x.el (from the emacswiki)
timeclock-setup.el

Download these, installing them somewhere in your PATH:

Do these set-up commands in a shell window (though, timeclock-setup.el should do this for you, now):

  mkdir ~/.timeclock
  touch ~/.timeclock/default.log

using it

This displays the timeclock-x.el help screen: C-x t h.

You clock-in on a project by doing a C-x t i and then giving it a project name (note: for each project, choose a short, unique string that you won't have any trouble getting right every time you clock-in).

You clock-out on a project by doing a C-x t o. Give it a "reason" string if you like, though it's not necesary (and I don't use 'em myself), with timeclock-x you'll then be asked if you want to type in a comment about what you were doing (personally, I always do... and I wish I could get that question to go away, since I always type y).

You can read (or edit... carefully) your time log file by doing a C-x t v.

Can't remember if you're clocked in or out? Do a C-x t s to see your status. Or just look at the mode-line, if you've got the timeclock-modeline-display feature turned on.

To see a list of project names in use already, use the "timeclock-display-project-names" command, bound to C-x t N. Or alternately, look at the variable: timeclock-project-list.

When you want a report of how you've spent your time, open a file where you'd like to insert the report, and do a C-x t R. Note: clocking out first is a good idea (otherwise you won't see any time for the current open period).

At present this report covers all the data in the ~/.timeclock/default.log file. So you'll need to delete information for days and/or projects you don't want to include in the final report. If you want reports that cover only a particular time period, it might make sense to periodically archive that log file and start over again.

todo list

Someone must have written timeclock report code already, I just got tired of looking. Continue the search? In general, I have a lot to learn about org-mode, diary, calender, planner, and so on...
Add a way to restrict the summary report to a particular project and/or time period. It's easy enough to add these features to the perl script timeclock_project_hours_report, but what would be a good emacs interface, e.g. to specify a time period (perhaps the default should be the current two week period?).
If you use timeclock religiously, than your emacs will always know what project you're working on. You could use this for project-specific customizations (e.g. indenting style might change depending on who you're working for at the moment). Look at: mk-project.html, or over here. Note, most of the competition likes to infer the project from the directory: ProjectSettings.
When you use a project name that's not in use already, timeclock should ask you if that's okay: that would help avoid errors without requiring that you declare valid projects first.
If you religiously enter comments after you clock-out you should (1) be able to get it to stop asking if you want to do it, and just assume you're going to (2) there should be a way to report those comments easily -- list all relevant comments when you print a summation of hours?
I find that my comments about what I was just doing are essentially identical to my version control check-in messages, and that I often want to do both operations at the same time. Maybe they should be combined? Possibly: set an option in timeclock*.el, and when you clock-out, your emacs should do a version control check-in automatically, using the comment you supply.
Note: most project-oriented approaches like to infer the project from the directory... could we do it the other way around? Use just the current timeclock project to infer which directories are associated with a project? (For the feature mentioned above one would need to know which files to check-in when you clock-out.)
Need a feature to move "dead" projects into another file, without deleting the data.
After clocking out, the window displaying the buffer you were working in gets lost.

Motivation

We need to work around some bugs in timeclock-x.el:

In order to get started, I needed to manually create a default.log:
```
  mkdir ~/.timeclock
  touch ~/.timeclock/default.log
```
This isn't documented anywhere, but without this I was seeing a bunch of number-or-marker-p errors from anything involving the modeline. That happens during set-up if you're doing this:
```
  (timeclock-modeline-display 1) ;; if you want modline display
```
And if you don't do that, it happens the first time you try to clock in.
The info page "39.14 Summing Time Intervals" specifically says:
```
  The timeclock feature adds up time intervals, so you can (for instance)
  keep track of how much time you spend working on particular projects.
```
But that doesn't square with my experience. That's why I went looking at other things like timeclock-x.el, and eventually added my own report feature using a perl/elisp lash-up.
The timeclock-x help screen refers to these commands:
```
    control x  t  g  t timeclock-generate-timesheet
    control x  t  g  r timeclock-generate-report
```
But the function timeclock-generate-timesheet is not actually defined anywhere.

Unfortunately, my email to the author of timeclock-x.el is bouncing. Anyone know what happened to: Kahlil HODGSON <dorge@tpg.com.au>?
Maybe this address is more current: kahlil.hodgson@arp.anu.edu.au

what extensions are in timeclock-x.el?

What does timeclock-x.el actually do for you?

Instead of logging to the ~/.timelog file it logs to ~/.timeclock/default.log.
The format of the new log is a little different, it has room after each clock-out to enter a multi-line comment about what you were doing.
There are some convenience routines for defining key-bindings easily, and so on.

And that might actually be it. I get the feeling there was supposed to be a timeclock-report.el file as well, but it doesn't seem to be out there any where.

other ways of doing it

There are (or are supposed to be) other ways of doing this, (see TimeTracking on the emacs wiki), in particular I have a certain pervese interest in org-mode (an emacs package written by GTD cultists).

This looks like the org-mode solution: Clocking Time with Emacs Org.
Of course, the trouble with this sort of big, integrated system is the presumption that you're using the whole thing... You can track your time on different tasks by working directly from the task list! Uh... I have to enter a task list first? Maybe I'll look into this later....

And also, this particular project.el (I doubt it's the only one) looks like it's another way of doing time-tracking.

Joseph Brenner, 10 Jun 2009