tracker - run App::TimeTracker
version 3.010
# initialize tracker for the 'Some-Project' directory ~/perl/Some-Project$ tracker init ~/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 command line.
tracker
Custom commands or adaptations to your workflow can be implemented via an "interesting" set of Moose-powered plugins. You can configure different sets of plugins for different jobs or projects.
Tip: Use tracker plugins to list all installed plugins. Read more about each plugin in App::TimeTracker::Command::PLUGIN-NAME.
tracker plugins
App::TimeTracker::Command::PLUGIN-NAME
Up to version 2.028 a lot of plugins where included in the main distribution App-TimeTracker. To make installation easier and faster, all non-core command plugins have been moved into distinct, standalone distributions.
App-TimeTracker
The following plugins are affected:
App::TimeTracker::Git (which also includes SyncViaGit)
App::TimeTracker::RT
App::TimeTracker::TellRemote (which was called Post2IRC earlier)
App::TimeTracker::Overtime has been removed, while the idea is nice, the API and implementation are not good enough.
App::TimeTracker::TextNotify has been removed.
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:
~$ cpanm App::TimeTracker --> Working on App::TimeTracker Fetching http://www.cpan.org/authors/id/D/DO/DOMM/App-TimeTracker-3.004.tar.gz ... OK Configuring App-TimeTracker-3.004 ... OK Building and testing App-TimeTracker-3.004 ... OK Successfully installed App-TimeTracker-3.004 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
CPAN.pm is available on ancient Perls, and feels a bit ancient, too.
cpan App::TimeTracker
To install App::TimeTracker from a tarball, 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
Clone the repository if you have not already done so, and enter the App-TimeTracker directory:
~$ git clone git@github.com:domm/App-TimeTracker.git ~$ cd App-TimeTracker
App-TimeTracker uses Dist::Zilla to build, test and install the code, hence this must be installed first, e.g. with cpanm:
cpanm
~/path/to/App-Tracker$ cpanm Dist::Zilla
Now install the distribution's dependencies, test and install in the usual manner for Dist::Zilla projects:
Dist::Zilla
~/path/to/App-Tracker$ dzil listdeps --missing | cpanm ~/path/to/App-Tracker$ dzil test ~/path/to/App-Tracker$ dzil install
The first time you run tracker, it will create the directory ~/.TimeTracker and generate an empty tracker.json core config file there.
~/.TimeTracker
tracker.json
In the root directory of the project you want to track time for, do tracker init. This will set up this directory for time-tracking. See below for more information on the config files and the merging of config files.
tracker init
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 project 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).
Call tracker start when you start working on a 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 TellRemote plugins for maximum laziness.
git
RT
TellRemote
The first step is to add a setting to the tracker config file in your project directory. Or you could add those settings to a config file in a parent directory, see Configuration for more information about that.
~/revdev/Some-Project$ cat .tracker.json { "plugins" : [ "Git", "RT", "TellRemote", ], "tell_remote" : { "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 slightly 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 happened:
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 usual 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, repetitive tasks (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 spent working on this task is calculated (and also stored).
start
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 can just use the SyncViaGit plugin!
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).
Tracking files
The filename of a tracking file looks like 'YYYYMMDD-HHMMSS_$project.trc', for example: 20110811-090437_App_TimeTracker.trc.
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.
Any time 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 reporting 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.
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 settings 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
Sometimes 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 separate projects. But I want App-TimeTracker-Gtk2TrayIcon to be a sub-project of App-TimeTracker, without having to change the directory structure.
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' ],
Thomas Klausner <domm@plix.at>
This software is copyright (c) 2011 - 2021 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 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.