Timetrap

Timetrap is a simple command line time tracker written in ruby. It provides an easy to use command line interface for tracking what you spend your time on.

Getting Started

To install:

$ gem install timetrap

This will place a t executable in your path.

If you would like to build the latest master from source:

$ git clone https://github.com/samg/timetrap
$ cd timetrap
$ gem build timetrap
$ gem install timetrap_X.X.X.gem

If you have errors while parsing the documentation, use --no-document option when installing the gem, or other option is to gem install rdoc before installing the timetrap. This is a known issue from rdoc

Basic Usage

$ # get help
$ timetrap --help
$ # or
$ t --help

Timetrap maintains a list of timesheets.

$ # create the "coding" timesheet
$ t sheet coding
Switching to sheet coding

All commands can be abbreviated.

$ # same as "t sheet coding"
$ t s coding
Switching to sheet coding

Each timesheet contains entries. Each entry has a start and end time, and a note associated with it. An entry without an end time set is considered to be running.

You check in to the current sheet with the in command.

$ # check in with "document timetrap" note
$ t in document timetrap
Checked into sheet "coding".

Commands like display and now will show you the running entry.

$ t display
Timesheet: coding
    Day                Start      End        Duration   Notes
    Sun Nov 28, 2010   12:26:10 -            0:00:03    document timetrap
                                             0:00:03
    ---------------------------------------------------------
    Total                                    0:00:03

$ t now
*coding: 0:01:02 (document timetrap)

If you make a mistake use the edit command.

$ # edit the running entry's note
$ t edit writing readme
Editing running entry

You check out with the out command.

$ t out
Checked out of entry "document timetrap" in sheet "coding"

Running edit when you're checked out will edit the last entry you checked out of.

$ t edit --append "oh and that"
Editing last entry you checked out of

You can edit entries that aren't running using edit's --id or -i flag. t display --ids (or t display -v) will tell you the ids.

$ # note id column in output
$ t d -v
Timesheet: coding
Id  Day                Start      End        Duration   Notes
43  Sun Nov 28, 2010   12:26:10 - 13:41:03   1:14:53    writing readme
                                             1:14:53
    ---------------------------------------------------------
    Total                                    1:14:53

$ # -i43 to edit entry 43
$ t e -i43 --end "2010-11-28 13:45"
Editing entry with id 43

$ t d
Timesheet: coding
    Day                Start      End        Duration   Notes
    Sun Nov 28, 2010   12:26:10 - 13:45:00   1:18:50    writing readme
                                             1:18:50
    ---------------------------------------------------------
    Total                                    1:18:50

Natural Language Times

Commands such as in, out, edit, and display have flags that accept times as arguments. Any time you pass Timetrap a time it will try to parse it as a natural language time.

This is very handy if you start working and forget to start Timetrap. You can check in 5 minutes ago using in's --at flag.

$ t in --at "5 minutes ago"

Command line flags also have short versions.

$ # equivalent to the command above
$ t i -a "5 minutes ago"

You can consult the Chronic gem (https://github.com/mojombo/chronic) for a full list of parsable time formats, but all of these should work.

$ t out --at "in 30 minutes"
$ t edit --start "last monday at 10:30am"
$ t edit --end "tomorrow at noon"
$ t display --start "10am" --end "2pm"
$ t i -a "2010-11-29 12:30:00"

Output Formats

Built-in Formatters

Timetrap has built-in support for 6 output formats.

These are text, csv, ical, json, and ids

The default is a plain text format. (You can change the default format using t configure).

$ t display
Timesheet: coding
    Day                Start      End        Duration   Notes
    Mon Apr 13, 2009   15:46:51 - 17:03:50   1:16:59    improved display functionality
                       17:25:59 - 17:26:02   0:00:03
                       18:38:07 - 18:38:52   0:00:45    working on list
                       22:37:38 - 23:38:43   1:01:05    work on kill
                                             2:18:52
    Tue Apr 14, 2009   00:41:16 - 01:40:19   0:59:03    gem packaging
                       10:20:00 - 10:48:10   0:28:10    working on readme
                                             1:27:13
    ---------------------------------------------------------
    Total                                    3:46:05

The CSV formatters is easy to import into a spreadsheet.

$ t display --format csv
start,end,note,sheet
"2010-08-21 11:19:05","2010-08-21 12:12:04","migrated site","coding"
"2010-08-21 12:44:09","2010-08-21 12:48:46","DNS emails and install email packages","coding"
"2010-08-21 12:49:57","2010-08-21 13:10:12","A records","coding"
"2010-08-21 15:09:37","2010-08-21 16:32:26","setup for wiki","coding"
"2010-08-25 20:42:55","2010-08-25 21:41:49","rewrote index","coding"
"2010-08-29 15:44:39","2010-08-29 16:21:53","recaptcha","coding"
"2010-08-29 21:15:58","2010-08-29 21:30:31","backups","coding"
"2010-08-29 21:40:56","2010-08-29 22:32:26","backups","coding"

iCal format lets you get your time into your favorite calendar program (remember commands can be abbreviated).

$ t d -f ical > MyTimeSheet.ics

The ids formatter is provided to facilitate scripting within timetrap. It only outputs numeric id for the entries. This is handy if you want to move all entries from one sheet to another sheet. You could do something like this:

$ for id in `t display sheet1 -f ids`; do t edit --id $id --move sheet2; done
editing entry #36
editing entry #37
editing entry #44
editing entry #46

A json formatter is provided because hackers love json.

$ t d -fjson

Custom Formatters

Timetrap tries to make it easy to define custom output formats.

You're encouraged to submit these back to timetrap for inclusion in a future version.

To create a custom formatter you create a ruby class and implement two methods on it.

As an example we'll create a formatter that only outputs the notes from entries.

To ensure that timetrap can find your formatter put it in ~/.timetrap/formatters/notes.rb. The filename should be the same as the string you will pass to t d --format to invoke it. If you want to put your formatter in a different place you can run t configure and edit the formatter_search_paths option.

All timetrap formatters live under the namespace Timetrap::Formatters so define your class like this:

class Timetrap::Formatters::Notes
end

When t display is invoked, timetrap initializes a new instance of the formatter passing it an Array of entries. It then calls #output which should return a string to be printed to the screen.

This means we need to implement an #initialize method and an #output method for the class. Something like this:

class Timetrap::Formatters::Notes
  def initialize(entries)
    @entries = entries
  end

  def output
    @entries.map{|entry| entry[:note]}.join("\n")
  end
end

Now when I invoke it:

$ t d -f notes
working on issue #123
working on issue #234

Timetrap Formatters Repository

A community focused repository of custom formatters is available at https://github.com/samg/timetrap_formatters.

Harvest Integration

For timetrap users who use [Harvest][harvest] to manage timesheets, [Devon Blandin][dblandin] created [timetrap-harvest][timetrap-harvest], a custom formatter which allows you to easily submit your timetrap entries to Harvest timesheets.

See its [README][timetrap-harvest] for more details.

Toggl Integration

For timetrap users who use [Toggl][toggl] to manage timesheets, [Miguel Palhas][naps62] created [timetrap-toggl][timetrap-toggl] (a fork of the [timetrap-harvest][timetrap-harvest] integration mentioned above.

Like the Harvest integration, this one allows you to easily submit your timetrap entries to Toggl.

See its [README][timetrap-toggl] for more details.

AutoSheets

Timetrap has a feature called auto sheets that allows you to automatically select which timesheet to check into.

Timetrap ships with a couple auto sheets. The default auto sheet is called dotfiles and will read the sheetname to check into from a .timetrap-sheet file in the current directory.

Here are all the included auto sheets

You can specify which auto sheet logic you want to use in ~/.timetrap.yml by changing the auto_sheet value.

Custom AutoSheets

It's also easy to write your own auto sheet logic that matches your personal workflow. You're encouraged to submit these back to timetrap for inclusion in a future version.

To create a custom auto sheet module you create a ruby class and implement one method on it #sheet. This method should return the name of the sheet timetrap should use (as a string) or nil if a sheet shouldn't be automatically selected.

All timetrap auto sheets live under the namespace Timetrap::AutoSheets

To ensure that timetrap can find your auto sheet put it in `~/.time