NAME

tracker - run App::TimeTracker

VERSION

version 2.014

SYNOPSIS

~/perl/Some-Project$ tracker start
Started working on Some-Project at 09:03:41

~/perl/Some-Project$ tracker stop
Worked 00:07:42 on Some-Project

DESCRIPTION

tracker is the front end script to App::TimeTracker. tracker allows you to easily track and report the time you spend on various jobs, projects, tasks etc from the commandline.

Custom commands or adaptions to your workflow can be implemented via an "interesting" set of Moose-powered plug-ins. You can configure different sets of plug-ins for different jobs or projects.

Tip: Use tracker plugins to list all installed plugins. Read more about each plug-in in App::TimeTracker::Command::PLUGIN-NAME.

INSTALLATION

App::TimeTracker is a Perl application, and thus requires a rencent Perl (>= 5.10). It also reuses a lot of code from CPAN.

From CPAN

The easiest way to install the current stable version of App::TimeTracker is via CPAN. There are several different CPAN clients available:

cpanminus

The new and shiny CPAN client!

~$ cpanm App::TimeTracker
--> Working on App::TimeTracker
Fetching http://search.cpan.org/CPAN/authors/id/D/DO/DOMM/App-TimeTracker-2.009.tar.gz ... OK
Configuring App-TimeTracker-2.009 ... OK
Building and testing App-TimeTracker-2.009 ... OK
Successfully installed App-TimeTracker-2.009
1 distribution installed

If you don't have cpanminus installed yet, install it right now:

~$ curl -L http://cpanmin.us | perl - --sudo App::cpanminus

CPANPLUS

CPANPLUS comes preinstalled with recent Perls (5.10 and newer).

cpanp i App::TimeTracker

CPAN.pm

CPAN.pm is available on ancient Perls, and feels a bit ancient, too.

cpan App::TimeTracker

From a tarball or git checkout

To install App::TimeTracker from a tarball or a git checkout, do the usual CPAN module install dance:

~/perl/App-TimeTracker$ perl Build.PL
~/perl/App-TimeTracker$ ./Build
~/perl/App-TimeTracker$ ./Build test
~/perl/App-TimeTracker$ ./Build install  # might require sudo

CONFIGURATION

App::TimeTracker uses a bunch of config files in JSON format. The config files valid for a specific instance of tracker are collected by walking the directory tree up from the current working directory, and merging all .tracker.json files that are found, plus the main config file ~/.TimeTracker/tracker.json.

You can use this tree of config files to define general settings, per job settings and per project settings, while always reusing the configuration defined in the parent. I.e. the config settings sort of override the values defined further up in the tree.

Anytime you call tracker, we look up from your current directory until we find the first .tracker.json file. This file marks the current project.

See App::TimeTracker::Command::Core and the various plugins for valid config parameters.

The different config files

Main config file: ~/.TimeTracker/tracker.json

The main config file lives in a directory named .TimeTracker located in your home directory (as defined by File::HomeDir). All other config files inherit from this file. You can, for example, use this file to define plugins you always want to use

List of projects: ~/.TimeTracker/projects.json

This file lists all the projects App::TimeTracker knows of on this machine. The content is autogenerated, so please do not edit it by hand. We use this file to locate all your working directories for the various reporing commands.

Per project config file: your-project/.tracker.json

Besides being the last node in the tree of the currently valid configuration, this file also defines the containing directory as a project.

Example

Given this directory structure:

~/.TimeTracker/tracker.json
~/job/.tracker.json
~/job/project/.tracker.json

If you hit start in ~/job/project/, all three of those config files will be merged and the resulting hash will be used as the current configuration.

If you hit start in ~/job/, only ~/job/.tracker.json and ~/.TimeTracker/tracker.json will be used.

This allows you to have global default settings, different default setting for different jobs, and fine tuned settings for each project. Of course you can have as many levels of configs as you want.

Tip: Use tracker show_config to dump the current configuration.

Using a different tree

Sometime you do not want to arrange your projects in the hierarchical way expected by App::TimeTracker:

~/perl/App-TimeTracker/.tracker.json
~/perl/App-TimeTracker-Gtk2TrayIcon/.tracker.json

Both App-TimeTracker and App-TimeTracker-Gtk2TrayIcon live in the same directory and thus would be considered seperate projects. But I want App-TimeTracker-Gtk2TrayIcon to be a sub-project of App-TimeTracker, without having to change the directory structure.

The solution: parent

In any config file you can define a key called parent. If this key is defined, the config-walker will use that project as the parent, and ignore the directory structure:

~/perl/App-TimeTracker-Gtk2TrayIcon$ cat .tracker.json
{
  "project":"App-TimeTracker-Gtk2TrayIcon",
  "parent":"App-TimeTracker"
}

And here's the relevant output of tracker show_config:

'_used_config_files' => [
  '/home/domm/perl/App-TimeTracker-Gtk2TrayIcon/.tracker.json',
  '/home/domm/perl/App-TimeTracker/.tracker.json',
  '/home/domm/perl/.tracker.json',
  '/home/domm/.TimeTracker/tracker.json'
],

USAGE

Initial Setup

Call tracker init to set up a directory for time-tracking. tracker init will create a config file called .tracker.json in your current directory. Use this file to load plugins for this projects and/or override and amend the configuration inherited from parent projects.

See Configuration for more information on how to configure tracker for your project(s).

Basic Usage

Call tracker start when you start working on some project, and tracker stop when you're done:

~/work/some_project$ tracker start
Started working on some_project at 13:06:20

~/work/some_project$ hack .. hack .. hack

~/work/some_project$ tracker stop
Worked 01:43:07 on some_project

To see how long you worked, use tracker report:

~/work/some_project$ tracker report --this day
work                     02:15:49
   some_project             01:43:07
   another_project          00:32:42
perl                     02:23:58
   App-TimeTracker          02:23:58
total                    04:39:47

Advanced Usage with git, RT and IRC

By using some Plugins we can make tracker a much more powerful tool. Let's use the git, RT and Post2IRC plugins for maximum lazyness.

The first step is to add some setting to the tracker config file to your project directory. Or add those settings to a config file in a parent directory, see Configuration for more information on that.

~/revdev/Some-Project$ cat .tracker.json
{
  "plugins" : [
    "Git",
    "RT",
    "Post2IRC",
  ],
  "post2irc" : {
    "secret" : "bai0uKiw",
    "host" : "http://devbox.vpn.somewhere.com/"
  },
  "rt" : {
    "set_owner_to" : "domm",
    "timeout" : "5",
    "update_time_worked" : "1",
    "server" : "https://somewhere.com/rt",
    "username" : "revbot"
    "password" : "12345",
  }
}

After setting everything up, we can do a simple (but sligtly amended) tracker start:

~/revdev/Some-Project$ tracker start --rt 1234
Started working on SomeProject (RT1234) flux capacitor needs more jigawatts at 15:32
Switched to a new branch 'RT1234_flux_capacitor_needs_more_jigawatts'

While this output might not seem very impressive, a lot of things have happend:

A new local git branch (based on the name of the RT ticket 1234) has been set up and checked out.
You have been assigned the owner of this ticket in RT.
A message has been posted in the internal IRC channel, informing your colleagues that you're now working on this ticket.
And of course we now keep track of the time!

As soon as you're done, you do the ususal tracker stop

~/revdev/Some-Project$ tracker stop
Worked 00:15:42 on some_project

Which does the following:

Calculate the time you worked and store it locally in the tracking file.
Post the time worked to RT.
Post a message to IRC.
git checkout master; git merge $branch is not performed, but you could enable this by using the command line flag --merge.

Even if those steps only shave off a few minutes per ticket, those are still a few minutes you don't have to spend on doing boring, repetative task (which one tends to forget / repress).

Tracking Files

Each time you start a new task, a so-called tracking file will be created. This file contains all information regarding the task you're currently working on (provided by App::TimeTracker::Data::Task, serialized to JSON via MooseX::Storage). If you call stop, the current time is stored into the tracking file and the time spend working on this task is calculated (and also stored).

All tracking files are plain text files containing JSON. It is very easy to synchronize them on different machines, using anything from rsync to version control systems. Or you just can use the SyncViaGit plug-in!

tracking files are stored in ~/.TimeTracker in a directory hierarchy consisting of the current year and the current month. This makes it easy (easier..) to find a specific tracking file in case you need to make some manual corrections (an interface for easier editing of tracking files is planned).

The filename of a tracking file looks like 'YYYYMMDD-HHMMSS_$project.trc', for example: 20110811-090437_App_TimeTracker.trc.

SOURCE CODE

git

We use git for version control and maintain a public repository on github.

You can find the latest version of App::TimeTracker here:

https://github.com/domm/App-TimeTracker

If you want to work on App::TimeTracker, add a feature, add a plugin or fix a bug, please feel free to fork the repo and send us pull requests to merge your changes.

To report a bug, please do not use the issues feature from github. Use RT instead.

CPAN

App::TimeTracker is distributed via CPAN, the Comprehensive Perl Archive Network. Here are a few different views into the CPAN, offering slightly different features:

Viewing and reporting Bugs

We use rt.cpan.org (thank you BestPractical) for bug reporting. Please do not use the issues feature of github! We pay no attention to those...

Please use this URL to view and report bugs:

https://rt.cpan.org/Public/Dist/Display.html?Name=App-TimeTracker

AUTHOR

Thomas Klausner <domm@cpan.org>

COPYRIGHT AND LICENSE

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

To install App::TimeTracker, copy and paste the appropriate command in to your terminal.

cpanm

cpanm App::TimeTracker

CPAN shell

perl -MCPAN -e shell
install App::TimeTracker

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)