timewriter

Minimal time logs tracker. Runs on Node.js. Features:

Friction-free time logging. Just type t shopping in the grocery to start a task.
Everything in the terminal. It's a Node.js command-line app that runs anywhere Node can. (even Windows!)
Built for humans who love text editors. Time logs are stored in a human-readable format that you can (should!) edit yourself.
Portable data. Aside from its human-readable format, you can easily export your data to json or csv.

Install

Install it via npm:

npm install -g timewriter

To make things easier, add this to your ~/.profile. (optional)

alias t="timewriter --file ~/.timelogs"

Note: the examples below assume that you have the alias above. If you choose not to to use it, assume that the t below is timewriter.

Get started

Log a task by typing t <thing-to-do>. (By convention, the first word is ideally the project name). For instance:

$ t Jsconf email speakers
# ...starts the task "Jsconf email speakers"

Stop it using t stop:

$ t stop
# ...stops the current task

You may also issue a reason to stop:

$ t stop coffee break
# ...stops the current task for the reason of "coffee break"

View the status with simply t:

$ t

  september 18, 2013

  1:30pm     Jsconf email speakers                                     52m
  2:22pm     ⋅⋅ coffee break                                            8m
  2:30pm     Jsconf check ticket sales                               1h 5m
  3:35pm     ⋅⋅ break                                                   3m
  3:38pm  ✓  Errands grocery

Catching up

Oops. Did you start working and forget to run your timer? No problem, just use add an offset in the format +<minutes>. Example:

$ t Misc coffee +3
# ...starts "Misc coffee" as if you ran it 3 mins ago

Storage

Everything is stored in a human-editable format into ~/.timelogs (use --file to change the location). This means you can add, edit, delete and rearrange entries using your favorite text editor.

$ cat ~/.timelogs

[2013-09-16 mon]
1:14pm = Misc write emails
2:42pm = Misc balance checkbook
3:00pm = ----

[2013-09-18 wed]
3:14pm = Jsconf email speakers
3:59pm = -- coffee break --
4:09pm = Jsconf check ticket sales
4:25pm = Errands grocery

Looking up entries

View entries from any date by using t <date>. It supports natural language parsing:

$ t yesterday
$ t aug 2
$ t last friday

Query a date range by using t <date> - <date>:

$ t last monday - last friday
$ t aug 2 - aug 10
$ t last month - now

Or all:

$ t all

Exporting

Export your data by using t <date> --format json:

$ t all --format json
{
  entries: [
    {
      type: "task",
      date: "2013-09-18T05:32:47.333Z",
      endDate: "2013-09-18T05:32:47.333Z",
      duration: 60000,
      project: "Jsconf",
      task: "Email speakers"
    }, ...
  ]
}

Or --format csv if you so please: (actually tab-separated; great for pasting into Google Docs)

$ t all --format csv
task  2013-09-18     3:45pm  4:42pm   61000    Jsconf    email speakers
task  2013-09-18     4:42pm  4:5Apm   43000    Jsconf    check tickets

--help

$ tw --help

  Usage: tw [options]

  Options:

    -h, --help         output usage information
    -V, --version      output the version number
    -f, --file <path>  the data file [~/.timelogs]

  Usage:

    tw                             # show current status

    tw <task>                      # start working
    tw start <task>                # start working
    tw start <task> +<N>           # start working, offset N minutes
    tw stop [<reason>]             # stop working

    tw <date>                      # show entries
    tw <date> - <date>             # show entries for date range

  Examples:

    tw myproject                   # start working on "myproject"
    tw stop                        # stop tracking
    tw stop lunch break            # stop tracking and log the reason
    tw 2 days ago                  # show entries from 2 days ago

rstacruz/Readme.md