present a project: traq

In the last post regarding open source side projects I presented revisioneer, an API to track application deployments.

Today I’ll be showcasing traq, a command line application which tracks your times. I’ve also blogged about it before.

The initial proof of concept was entirely written in bash with a focus on simplicity and understandability. This meant that traq uses a simple folder structure and plain text files to store the tracked times.

As a programmer I tend to be always working with the terminal and being forced to use my mouse and to browse a GUI annoys the hell out of. It just takes far too much time. So my goal was having a tool which could manage all my times, both personal and work relateded. It should be easy to use and give basic evaluation features.

Here’s an example usage, taken from my average work day:

[08:10] $ traq -p mindmatters work    # some time later…
[10:00] $ traq -p mindmatters meeting # …off to something completly different…
[10:17] $ traq -p mindmatters work    # done /w the meeting. back to work
[12:00] $ traq -p mindmatters stop    # short break
[12:32] $ traq -p mindmatters work
[15:11] $ traq -p mindmatters stop    # playing table football
[15:23] $ traq -p mindmatters work
[16:59] $ traq -p mindmatters stop    # …that's it. done for today

Under the hood, this generates a text file like this:

Fri Aug 15 08:10:39 +0200 2014;#work;
Fri Aug 15 10:00:41 +0200 2014;#meeting;
Fri Aug 15 10:17:42 +0200 2014;#work;
Fri Aug 15 12:00:45 +0200 2014;stop;
Fri Aug 15 12:32:15 +0200 2014;#work;
Fri Aug 15 15:11:00 +0200 2014;stop;
Fri Aug 15 15:23:11 +0200 2014;#work;
Fri Aug 15 16:59:51 +0200 2014;stop;

Notice the -p flag which allows me to switch to different projects.

At the end of the day I need to the enter the times in harvest because we use it at work. Traq is able to sum up everything properly and display a short summary:

$ traq -p mindmatters -e
2014-08-15
#work:7.8083
#meeting:0.2836
%%

Since time tracking is a sensitive topic traq had tests from the very beginning. Initially I was using bats for this.

Using bash was a good start, but the had some limitations:

evaluation quickly became slow, even for small datasets (e.g. a weeks worth of data)
portability was painful.
I wanted traq to work on Linux and Darwin. Traq used date internally to convert & generate timestamps and the parameters are completly different on both OSes.

After about a year I decided to rewrite it using Go - which turned out to be a really good decision.

The limitations went away. I was able to add more test cases and at the same time making the code base more concise and easier to understand.

Having used traq for all my time tracking for nearly 2 years now using a simple, folder based structure as data store also proofed to be a good decision.

There are only two minor things I’d like to change, and the data storage allows for easy work arounds for both of them:

make the data storage pluggable, to allow sharing of times between devices.
I’m sometimes using my personal notebook at work and switching between notebooks always forces me to keep the folder in sync. There are workaround options available for this (e.g. dropbox).
add support for a plugin structure to handle timing.
this would allow me to easily push data to external services like Harvest, automatically. It’s a convenience feature which can also be worked around with a combination of atd and some scripting.

I’ve started a code spike regarding both ideas, but since traq works just fine it might take some time to finish them.

That’s about it. Next up: umsatz - the financial accounting app you can host yourself on a raspberry pi.

August 17, 2014

present a project: traq