#!/usr/bin/perl
use strict;
use warnings;
use App::TimeTracker::Proto;
binmode(STDOUT, ":utf8");
my $app = App::TimeTracker::Proto->new->run;
# ABSTRACT: run App::TimeTracker
# PODNAME: tracker
__END__
=pod
=encoding UTF-8
=head1 NAME
tracker - run App::TimeTracker
=head1 VERSION
version 2.024
=head1 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
=head1 DESCRIPTION
C<tracker> is the front end script to L<App::TimeTracker>. C<tracker>
allows you to easily track and report the time you spend on various
jobs, projects, tasks etc from the commandline.
Custom commands or adaptations to your workflow can be implemented via
an "interesting" set of L<Moose>-powered plugins. You can configure
different sets of plugins for different jobs or projects.
B<Tip:> Use C<tracker plugins> to list all installed plugins. Read more
about each plugin in C<App::TimeTracker::Command::PLUGIN-NAME>.
=head1 INSTALLATION
L<App::TimeTracker> is a L<Perl|http://perl.org> application, and thus requires
a recent Perl (>= 5.10). It also reuses a lot of code from
L<CPAN|http://cpan.org>.
=head2 From CPAN
The easiest way to install the current stable version of L<App::TimeTracker> is
via L<CPAN|http://cpan.org>. There are several different CPAN clients
available:
=head3 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 C<cpanminus> installed yet, L<install it right
now|http://search.cpan.org/dist/App-cpanminus/lib/App/cpanminus.pm#INSTALLATION>:
~$ curl -L http://cpanmin.us | perl - --sudo App::cpanminus
=head3 CPANPLUS
CPANPLUS comes preinstalled with recent Perls (5.10 and newer).
cpanp i App::TimeTracker
=head3 CPAN.pm
CPAN.pm is available on ancient Perls, and feels a bit ancient, too.
cpan App::TimeTracker
=head2 From a tarball or git checkout
To install L<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
=head1 CONFIGURATION
L<App::TimeTracker> uses a bunch of config files in JSON format. The config
files valid for a specific instance of C<tracker> are collected by walking
the directory tree up from the current working directory, and merging all
F<.tracker.json> files that are found, plus the main config file
F<~/.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 C<tracker>, we look up from your current directory until we
find the first C<.tracker.json> file. This file marks the current project.
See L<App::TimeTracker::Command::Core> and the various plugins for valid config
parameters.
=head2 The different config files
=head3 Main config file: ~/.TimeTracker/tracker.json
The main config file lives in a directory named F<.TimeTracker>
located in your home directory (as defined by L<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.
=head3 List of projects: ~/.TimeTracker/projects.json
This file lists all the projects L<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.
=head3 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.
=head2 Example
Given this directory structure:
~/.TimeTracker/tracker.json
~/job/.tracker.json
~/job/project/.tracker.json
If you hit C<start> in F<~/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 C<start> in F<~/job/>, only F<~/job/.tracker.json> and
C<~/.TimeTracker/tracker.json> will be used.
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.
B<Tip:> Use C<tracker show_config> to dump the current configuration.
=head2 Using a different tree
Sometimes you do not want to arrange your projects in the hierarchical way
expected by L<App::TimeTracker>:
~/perl/App-TimeTracker/.tracker.json
~/perl/App-TimeTracker-Gtk2TrayIcon/.tracker.json
Both C<App-TimeTracker> and C<App-TimeTracker-Gtk2TrayIcon> live in the same
directory and thus would be considered separate projects. But I want
C<App-TimeTracker-Gtk2TrayIcon> to be a sub-project of C<App-TimeTracker>,
without having to change the directory structure.
The solution: C<parent>
In any config file you can define a key called C<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 C<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'
],
=head1 USAGE
=head2 Initial Setup
Call C<tracker init> to set up a directory for time-tracking. C<tracker
init> will create a config file called F<.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 L<Configuration|/CONFIGURATION> for more information on how to configure C<tracker> for
your project(s).
=head2 Basic Usage
Call C<tracker start> when you start working on a project, and C<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 C<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
=head2 Advanced Usage with git, RT and IRC
By using some plugins we can make C<tracker> a much more powerful tool.
Let's use the C<git>, C<RT> and C<Post2IRC> plugins for maximum laziness.
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 L<Configuration|/CONFIGURATION> for more information about 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 slightly amended)
C<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:
=over
=item * A new local git branch (based on the name of the RT ticket 1234) has
been set up and checked out.
=item * You have been assigned the owner of this ticket in RT.
=item * A message has been posted in the internal IRC channel, informing
your colleagues that you're now working on this ticket.
=item * And of course we now keep track of the time!
=back
As soon as you're done, you do the usual C<tracker stop>
~/revdev/Some-Project$ tracker stop
Worked 00:15:42 on some_project
Which does the following:
=over
=item * Calculate the time you worked and store it locally in the tracking file.
=item * Post the time worked to RT.
=item * Post a message to IRC.
=item * C<git checkout master; git merge $branch> is not performed, but you
could enable this by using the command line flag C<--merge>.
=back
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).
=head2 Tracking Files
Each time you C<start> a new task, a so-called C<tracking file> will be
created. This file contains all information regarding the task you're
currently working on (provided by L<App::TimeTracker::Data::Task>,
serialized to JSON via L<MooseX::Storage>). If you call C<stop>, the current
time is stored into the C<tracking file> and the time spent working on this
task is calculated (and also stored).
All C<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
C<SyncViaGit> plugin!
C<Tracking files> are stored in F<~/.TimeTracker> in a directory
hierarchy consisting of the current year and the current month. This
makes it easy (easier..) to find a specific C<tracking file> in case
you need to make some manual corrections (an interface for easier
editing of C<tracking files> is planned).
The filename of a C<tracking file> looks like
'YYYYMMDD-HHMMSS_$project.trc', for example:
F<20110811-090437_App_TimeTracker.trc>.
=head1 SOURCE CODE
=head2 git
We use C<< git >> for version control and maintain a public repository on
L<github|http://github.com>.
You can find the latest version of L<App::TimeTracker> here:
L<https://github.com/domm/App-TimeTracker>
If you want to work on L<App::TimeTracker>, add a feature, add a plugin or fix
a bug, please feel free to L<fork|http://help.github.com/fork-a-repo/> the
repo and send us L<pull requests|http://help.github.com/send-pull-requests/>
to merge your changes.
To report a bug, please B<do not> use the C<< issues >> feature from github;
use RT instead.
=head2 CPAN
L<App::TimeTracker> is distributed via L<CPAN|http://cpan.org/>, the
Comprehensive Perl Archive Network. Here are a few different views of
CPAN, offering slightly different features:
=over
=item * L<https://metacpan.org/release/App-TimeTracker/>
=item * L<http://search.cpan.org/dist/App-TimeTracker/>
=back
=head1 Viewing and reporting Bugs
We use L<rt.cpan.org|http://rt.cpan.org> (thank you
L<BestPractical|http://rt.bestpractical.com>) for bug reporting. Please do
not use the C<issues> feature of github! We pay no attention to those...
Please use this URL to view and report bugs:
L<https://rt.cpan.org/Public/Dist/Display.html?Name=App-TimeTracker>
=head1 AUTHOR
Thomas Klausner <domm@cpan.org>
=head1 COPYRIGHT AND LICENSE
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.
=cut