OS X TextMate user? free time tracker: matewatch

September 14th, 2007

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

[Nov '08] For "[BUG] Bus Error" issues with rubyosa-0.4.0 see Nick's post.

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)

Posted by Ian White Filed in Code, Ian

13 Responses to “OS X TextMate user? free time tracker: matewatch”

Ian Says:
September 14th, 2007 at 04:31 PM

Oh yeah - an easy way to have it start at login is to save a terminal session with matewatch as the command. Then just add this to your startup items.

Here's a sample one http://svn.ardes.com/ardes/matewatch/matewatch.term

Kookoolen Says:
September 14th, 2007 at 04:35 PM

Another way to have it start at login is creating a com.ardes.matewatch.plist file in ~/Library/LaunchAgents with the following content:

            
            <?xml version="1.0"" encoding="UTF-8";?>
            <!DOCTYPE plist PUBLIC "-//Apple Computer//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
            <plist version="1.0">
            <dict>
              <key>Disabled</key>
              <false />
              <key>Label</key>
              <string>com.ardes.matewatch</string>
              <key>ProgramArguments</key>
              <array>
                <string>matewatch</string>
                <string>start</string>
              </array>
              <key>LowPriorityIO</key>
              <true />
              <key>Nice</key>
              <integer>1</integer>
            </dict>
            </plist>

Ian Says:
September 14th, 2007 at 04:36 PM
Kookoolen - that's obviously the best way! - unless you want a retro c64 stylee terminal window, and you want to see the output of matewatch :)
Jon Evans Says:
September 18th, 2007 at 02:37 PM
This looks very interesting - I've just installed it. I've got a hunch that, like you, I'm going to discover I'm spending a lot longer on projects than I've budgeted for.
Walther H Diechmann Says:
December 21st, 2007 at 01:43 PM
Hi, it's a wonderful idea - and I believe to have done exactly as "the doctor ordered", but when I do a 'matewatch report Test' (and I have done matewatch add Test /Users/Walther/tmp and can do matewatch list), this is what happens ============================= Test: report => Fri 21/Dec/07 ============================= No session data exists Would you have an idea to what I might be doing wrong? Best regards and a merry Christmas! Walther
Ian White Says:
December 21st, 2007 at 01:49 PM
Hi Walther, Have you actually opened Textmate on a file (as opposed to just folders) in /Users/Walther/tmp? If you run matewatch as follows:
```
matewatch start -v
```
And open some documents in textmate you should see it detect these docs. Email me at gmail dot com. ian.w.white
Phil Crosby Says:
June 4th, 2008 at 11:48 PM
Nice concept, I like it.
Henry Karpatskij Says:
July 27th, 2008 at 11:35 AM
This is really nice thing - I used to have some bloated time tracking software with all those invoicing features, which I didn't need, to track time spent on projects. It was inconvenient and frustrating. Thanks for the excellent product! However, there's one concern which I found one day. I was browsing the reports and found out that it hadn't recorded a single session that same day, even though I had worked the entire day on a project. The daemon is started when computer starts, so that wasn't the issue - I found out that the pid file has not been removed from the system when the computer has crashed and the daemon could not start. By removing the PID file I managed to get it working. But is there any way of getting the PID file automagically overwritten if the process does not exist? Would that cause problems somewhere else? My MBP crashes time to time, sometimes often, sometimes never, so it would help a lot if I didn't have to remember to remove the file each time it does.
Ray Drainville Says:
July 27th, 2008 at 02:58 PM

Henry,

Hi there, Ian’s away at present. Sorry to hear that you’re having problems with Matewatch. You haven’t mentioned it explicitly, but did you notify Matewatch of the project you’re working on? For instance, if you’re working on a project called MyProject located in ~/Projects/MyProject, you notify Matewatch via the command line like this:
```
matewatch add MyProject ~/Projects/MyProject
```
If you haven’t notified Matewatch of the project, it (of course) won’t watch it for you.

A further tip—I’d strongly recommend that you modify the preferences so that MW starts up with matewatch -v -r—that way it doesn’t keep track of TextMate when it’s in the background. I do this because I generally keep TM open overnight & early on was surprised by how much time I had “spent” working on a project :P
Henry Karpatskij Says:
July 27th, 2008 at 05:58 PM
Sure - the project is added to matewatch list and it has recorded sessions in the past. But since the daemon does not start at all, the sessions are not recorded. Perhaps Ian could drop a comment when he gets back from wherever he is. :-)
Henry Karpatskij Says:
July 27th, 2008 at 06:50 PM
I tweaked the code a bit, diff at http://spheroid.fi/tmp/matewatch.diff. Any side-effects here?
Nick Rutherford Says:
November 6th, 2008 at 06:07 PM
At present rubyosa has some issues:http://rubyforge.org/tracker/index.php?func=detail&aid=21223&group_id=1845&atid=7180 This solution makes it work again: http://www.dicianno.org/blog/2008/10/06/rubyosa-040-bus-error/
```
  sudo gem install libxml-ruby --version 0.3.8.4 
  sudo sed -i -e "s|require 'xml/libxml'|gem 'xml/libxml', '= 0.3.8.4'|" /Library/Ruby/Gems/1.8/gems/rubyosa-0.4.0/lib/rbosa.rb
```
Nick Rutherford Says:
November 8th, 2008 at 04:12 AM

Henry

I'll have a look at the diff and the issue you raised, and mention it again to Ian. He's been very busy with other work & plugin updates for new Rails.

This falls outside his regular work pattern so I'd imagine he's overlooked it, or forgotten.

Regards
Nick