What is Timebook?

Timebook is a command line utility that tracks your time without costing you any of it.

Preface

There are a few time tracking tools out there. I’ve used SlimTimer in the past, but having an extra window open is a pain, especially a browser window. As much as I love Firefox, I don’t want my paycheck to count on it not crashing.

So, I usually end up keeping a big Google Docs spreadsheet. I have different pages for different clients and columns for date, task, clock in time, clock out time, etc. It’s not a bad system, but it means clocking in takes me 30 seconds. Too much overhead.

So I was talking to Trevor about two weeks ago, and mentioned my frustration. “I wish there was a way I could track time by just entering “timer start ‘client’ ‘task-description’ on the command line.” He shot me a link to a python script he’s been using for a few years that does just that (though the syntax is a little different)! And ever since, we’ve been refining it and adding features. I find it incredibly useful – take a look!

Using Timebook

First, let’s take a look at the Timebook commands. Note that the base for timebook is “t” and you can use 1 letter shortcuts for every one of the timebook commands. So in the examples below, I’m going to use “t s” instead of “t switch”, etc.

$ t --help
Usage: t [OPTIONS] COMMAND [ARGS...]
 
where COMMAND is one of:
    alter - alter the description of the active period
    backend - open an the backend´s interactive shell
    display - display the current timesheet
    format - export a sheet to csv format
    in - start the timer for the current timesheet
    kill - delete a timesheet
    list - show the available timesheets
    now - show the status of the current timesheet
    out - stop the timer for the current timesheet
    running - show all running timesheets
    switch - switch to a new timesheet

Timebook will start you off on a timesheet called “default”. You’ll probably want to have different timesheets for different groups of tasks; say, different clients. Let’s say you have one for your client Acme. Switch to the Acme timesheet like this (it will be created as you start using it).

$ t s Acme

Now let’s say you’re going to spend an hour tightening widgets. Punch in like this.

$ t i tightening widgets

Pretty easy! Let’s say you’ve been working for a while and you wanted to be reminded what task you were on and how long you’d been on it. Try this command.

$ t
Acme: 0:40:48 (tightening widgets)

Clock out like this.

$ t o

Now let’s start a new task, and display our timesheet so far.

$ t i running errands
$ t d
Timesheet Acme:
Day            Start      End        Duration   Notes
Mar 19, 2009   14:47:59 - 16:30:28   1:42:29    tightening widgets
               16:30:33 -            0:00:03    running errands
                                     1:42:32    
Total                                1:42:32

Play around with some of the other commands. You can list your timesheets, display which ones are active, export your timesheet (even given a particular date range) as a csv (hopefully soon an excel doc).

Lots of fun stuff to play with. And it’s definitely the lightest weight timekeeping app I know of.

Installing Timebook

Linux

$ sudo apt-get install mercurial # if you don't already have mercurial
$ hg clone http://hg@bitbucket.org/trevor/timebook/
$ cd timebook 
$ sudo python setup.py install

Windows
coming soon
OS X
First get mercurial. Here’s one option: http://mercurial.berkwood.com/

$ hg clone http://hg@bitbucket.org/trevor/timebook/
$ cd timebook 
$ sudo python setup.py install