The Mechanical Turk

Tracking our time spent on projects has been a major pain for us. We've tried a few of the OS X solutions out there, and they all have some of the following problems:

• B L O A T E D - so many useless features
• You have to either turn the tracker on and off manually, which we invariably forget to do, or
• You can associate one application with turning the tracker on - which is not fine grained enough

So we rolled our own. matewatch simply checks what TextMate documents you're editing and records the intervals of time that those documents are frontmost in TextMate.

Howto

It's written in ruby (of course), and you need to grab rubygems, and install rubyosa and activesupport. (See the bottom of this post for instructions on this.)

Then install matewatch into a directory in your $PATH:

  svn export http://svn.ardes.com/ardes/matewatch/matewatch

Fire it up (in verbose mode to see what its doing)

  matewatch start -v

in another terminal, add a project, then do some work

  matewatch add rails_plugins ~/Development/rails_plugins

This is what the output looks like

  +++ Textmate active at Fri Sep 14 14:45:17 +0100 2007
  [#] plugins started at Fri Sep 14 14:45:27 +0100 2007
  --- Textmate inactive at Fri Sep 14 14:45:37 +0100 2007
  [ ] plugins stopped at Fri Sep 14 14:45:37 +0100 2007

Then, when you want to see how much time you've been hacking away

  matewatch report rails_plugins
  
  ======================================
  rails_plugins: report => Fri 14/Sep/07
  ======================================
   - 11/Sep/07:   0:00:35
   - 12/Sep/07:   4:40:01
   - 13/Sep/07:   2:35:16
   - 14/Sep/07:   0:00:10
   ----- TOTAL:   7:16:03 [7 hours, 30 minutes (15 min chunks)]

You can get a variety of reports. just do matewatch help to see what's available.

Sleepwatcher

If you install sleepwatcher (just the daemon, you don't need to install the startup item) then matewatch will interrupt sessions when the computer goes to sleep.

Happy tracking

We've just completed a small project that we estimated would take 14 hours - with matewatch we learnt that it took us closer to double that. It's turning out to be be a very useful little script.

If you find a bug, or have a feature request, let us know.

Installing dependencies

Ruby

See this guide for getting a suitable ruby on OS X

Rubygems

Get rubygems extract it, and set it up with

  sudo ruby setup.rb

gems

Now install the required gems

  sudo gem install activesupport
  sudo gem install rubyosa

All the options

This is the output of matewatch help

matewatch watches textmate and logs how long you are working on files in spec-
ified directories

USAGE

  matewatch COMMAND [OPTIONS]
  
  matewatch start
    Starts the project watcher
    
    --verbose               -v            show output
    --poll=<n>              -p <n>        poll every (n) seconds
    --require-frontmost     -r            require that textmate be frontmost
                                          application to log time data
  
  matewatch report [<name>]
    Show brief report of hours/minutes per day

    --hourly  OR  --session               show hourly/session report
    --from=<date>           -f <date>     from specified date
    --to=<date>             -t <date>     to specified date
    --day=<date>            -d <date>     for specified date

  matewatch list
    List projects being watched
    
  matewatch add <name> <path> [<position>]
    Add a project to the watch list
    
  matewatch remove <name>
    Remove a project from the watch list.  Copies the project data to
    a timestamped backup in /Users/ian/.matewatch
    
  matewatch move <name> <position>
    Move a project up or down the list

  matewatch pause
    Will pause the current matewatcher, 'matewatch start' will restart it

DATA

  If you want to get at the session data for your projects, you'll find them
  in /Users/ian/.matewatch.
  
  The files are YAML format, and so are easily editable/exportable.

    by Argument from Design (c) 2007 <http://www.ardes.com> (MIT License)