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...
Download these and install them to somwhere in your emacs load-path:
mkdir ~/.timeclock touch ~/.timeclock/default.log
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.
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.logThis 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 displayAnd 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-reportBut 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 <firstname.lastname@example.org>?
Maybe this address is more current: email@example.com
What does timeclock-x.el actually do for you?
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.