tracker - run App::TimeTracker
version 2.020
~/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
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.
tracker
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.
tracker plugins
App::TimeTracker::Command::PLUGIN-NAME
App::TimeTracker is a Perl application, and thus requires a recent Perl (>= 5.10). It also reuses a lot of code from CPAN.
The easiest way to install the current stable version of App::TimeTracker is via CPAN. There are several different CPAN clients available:
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:
cpanminus
~$ curl -L http://cpanmin.us | perl - --sudo App::cpanminus
CPANPLUS comes preinstalled with recent Perls (5.10 and newer).
cpanp i App::TimeTracker
CPAN.pm is available on ancient Perls, and feels a bit ancient, too.
cpan App::TimeTracker
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
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.
.tracker.json
See App::TimeTracker::Command::Core and the various plugins for valid config parameters.
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
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.
Besides being the last node in the tree of the currently valid configuration, this file also defines the containing directory as a project.
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.
start
If you hit start in ~/job/, only ~/job/.tracker.json and ~/.TimeTracker/tracker.json will be used.
~/.TimeTracker/tracker.json
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.
tracker show_config
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.
App-TimeTracker
App-TimeTracker-Gtk2TrayIcon
The solution: parent
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' ],
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.
tracker init
See Configuration for more information on how to configure tracker for your project(s).
Call tracker start when you start working on some project, and tracker stop when you're done:
tracker start
tracker stop
~/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:
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
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.
git
RT
Post2IRC
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.
git checkout master; git merge $branch
--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).
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).
tracking file
stop
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
SyncViaGit
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.
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.
issues
App::TimeTracker is distributed via CPAN, the Comprehensive Perl Archive Network. Here are a few different views into the CPAN, offering slightly different features:
https://metacpan.org/release/App-TimeTracker/
http://search.cpan.org/dist/App-TimeTracker/
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
Thomas Klausner <domm@cpan.org>
This software is copyright (c) 2011 by Thomas Klausner.
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.