/ 
App-TimeTracker-3.003
River stage two • 10 direct dependents • 10 total dependents
/ tracker

NAME

tracker - run App::TimeTracker

VERSION

version 3.003

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 command line.

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.

Note about (missing) Plugins

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.

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.

INSTALLATION

App::TimeTracker is a Perl application, and thus requires a recent 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

~$ 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

CPAN.pm

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

cpan App::TimeTracker

From a tarball

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

From a git checkout

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:

~/path/to/App-Tracker$ cpanm Dist::Zilla

Now install the distribution's dependencies, test and install in the usual manner for Dist::Zilla projects:

~/path/to/App-Tracker$ dzil listdeps --missing | cpanm
~/path/to/App-Tracker$ dzil test
~/path/to/App-Tracker$ dzil install

SETUP

The first time you run tracker, it will create the directory ~/.TimeTracker and generate an empty tracker.json core config file there.

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.

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.

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.

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 reporting 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 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.

Using a different tree

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.

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 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).

Basic Usage

Call tracker start when you start working on a 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 TellRemote 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 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.

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).

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 spent 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 can just use the SyncViaGit plugin!

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 of 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 software is copyright (c) 2011 - 2020 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.