diff --git a/bin/tracker b/bin/tracker index 86ed4a9..c67549e 100755 --- a/bin/tracker +++ b/bin/tracker @@ -27,98 +27,6 @@ C is the front end script to L. C 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 L-powered plugins. You can configure -different sets of plugins for different jobs or projects. - -B Use C to list all installed plugins. Read more -about each plugin in C. - -=head2 Note about (missing) Plugins - -Up to version 2.028 a lot of plugins where included in the main distribution -C. To make installation easier and faster, all non-core -command plugins have been moved into distinct, standalone distributions. - -The following plugins are affected: - -=over - -=item * App::TimeTracker::Git (which also includes SyncViaGit) - -=item * App::TimeTracker::RT - -=item * App::TimeTracker::TellRemote (which was called Post2IRC earlier) - -=item * App::TimeTracker::Overtime has been removed, while the idea is nice, the API and implementation are not good enough. - -=item * App::TimeTracker::TextNotify has been removed. - -=back - -=head1 INSTALLATION - -L is a L application, and thus requires -a recent Perl (>= 5.10). It also reuses a lot of code from -L. - -=head2 From CPAN - -The easiest way to install the current stable version of L is -via L. There are several different CPAN clients -available: - -=head3 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 C installed yet, L: - - ~$ curl -L http://cpanmin.us | perl - --sudo App::cpanminus - -=head3 CPAN.pm - -CPAN.pm is available on ancient Perls, and feels a bit ancient, too. - - cpan App::TimeTracker - -=head2 From a tarball - -To install L 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 - -=head2 From a git checkout - -Clone the repository if you have not already done so, and enter the -C directory: - - ~$ git clone git@github.com:domm/App-TimeTracker.git - ~$ cd App-TimeTracker - -C uses L to build, test and install the code, -hence this must be installed first, e.g. with C: - - ~/path/to/App-Tracker$ cpanm Dist::Zilla - -Now install the distribution's dependencies, test and install in the usual -manner for C projects: - - ~/path/to/App-Tracker$ dzil listdeps --missing | cpanm - ~/path/to/App-Tracker$ dzil test - ~/path/to/App-Tracker$ dzil install - =head1 SETUP The first time you run C, it will create the directory @@ -130,102 +38,6 @@ C. This will set up this directory for time-tracking. See below for more information on the config files and the merging of config files. -=head1 CONFIGURATION - -L uses a bunch of config files in JSON format. The config -files valid for a specific instance of C 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, we look up from your current directory until we -find the first C<.tracker.json> file. This file marks the current project. - -See L 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). 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 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 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 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 Use C 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: - - ~/perl/App-TimeTracker/.tracker.json - ~/perl/App-TimeTracker-Gtk2TrayIcon/.tracker.json - -Both C and C live in the same -directory and thus would be considered separate projects. But I want -C to be a sub-project of C, -without having to change the directory structure. - -The solution: C - -In any config file you can define a key called C. 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: - - '_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 @@ -363,45 +175,98 @@ The filename of a C looks like 'YYYYMMDD-HHMMSS_$project.trc', for example: F<20110811-090437_App_TimeTracker.trc>. -=head1 SOURCE CODE +=head1 CONFIGURATION -=head2 git +L uses a bunch of config files in JSON format. The config +files valid for a specific instance of C 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>. -We use C<< git >> for version control and maintain a public repository on -L. +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, we look up from your current directory until we +find the first C<.tracker.json> file. This file marks the current project. -You can find the latest version of L here: +See L and the various plugins for valid config +parameters. -L +=head2 The different config files -If you want to work on L, add a feature, add a plugin or fix -a bug, please feel free to L the -repo and send us L -to merge your changes. +=head3 Main config file: ~/.TimeTracker/tracker.json -To report a bug, please B use the C<< issues >> feature from github; -use RT instead. +The main config file lives in a directory named F<.TimeTracker> +located in your home directory (as defined by L). All +other config files inherit from this file. You can, for example, use +this file to define plugins you always want to use. -=head2 CPAN +=head3 List of projects: ~/.TimeTracker/projects.json -L is distributed via L, the -Comprehensive Perl Archive Network. Here are a few different views of -CPAN, offering slightly different features: +This file lists all the projects L 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. -=over +=head3 Per project config file: your-project/.tracker.json -=item * L +Besides being the last node in the tree of the currently valid +configuration, this file also defines the containing directory as a +project. -=item * L +=head2 Example -=back +Given this directory structure: -=head1 Viewing and reporting Bugs + ~/.TimeTracker/tracker.json + ~/job/.tracker.json + ~/job/project/.tracker.json -We use L (thank you -L) for bug reporting. Please do -not use the C feature of github! We pay no attention to those... +If you hit C in F<~/job/project/>, all three of those config +files will be merged and the resulting hash will be used as the +current configuration. -Please use this URL to view and report bugs: +If you hit C in F<~/job/>, only F<~/job/.tracker.json> and +C<~/.TimeTracker/tracker.json> will be used. -L +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 Use C 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: + + ~/perl/App-TimeTracker/.tracker.json + ~/perl/App-TimeTracker-Gtk2TrayIcon/.tracker.json + +Both C and C live in the same +directory and thus would be considered separate projects. But I want +C to be a sub-project of C, +without having to change the directory structure. + +The solution: C + +In any config file you can define a key called C. 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: + + '_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' + ], diff --git a/lib/App/TimeTracker.pm b/lib/App/TimeTracker.pm index 53cf5fd..492b4b2 100644 --- a/lib/App/TimeTracker.pm +++ b/lib/App/TimeTracker.pm @@ -301,7 +301,143 @@ __END__ Backend for the C command. See L and/or C for details. +=head1 INSTALLATION + +L is a L application, and thus requires +a recent Perl (>= 5.10). It also reuses a lot of code from +L. + +=head2 From CPAN + +The easiest way to install the current stable version of L is +via L. There are several different CPAN clients +available: + +=head3 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 C installed yet, L: + + ~$ curl -L http://cpanmin.us | perl - --sudo App::cpanminus + +=head3 CPAN.pm + +CPAN.pm is available on ancient Perls, and feels a bit ancient, too. + + cpan App::TimeTracker + +=head2 From a tarball + +To install L 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 + +=head2 From a git checkout + +Clone the repository if you have not already done so, and enter the +C directory: + + ~$ git clone git@github.com:domm/App-TimeTracker.git + ~$ cd App-TimeTracker + +C uses L to build, test and install the code, +hence this must be installed first, e.g. with C: + + ~/path/to/App-Tracker$ cpanm Dist::Zilla + +Now install the distribution's dependencies, test and install in the usual +manner for C projects: + + ~/path/to/App-Tracker$ dzil listdeps --missing | cpanm + ~/path/to/App-Tracker$ dzil test + ~/path/to/App-Tracker$ dzil install + +=head1 PLUGINS + +Custom commands or adaptations to your workflow can be implemented via +an "interesting" set of L-powered plugins. You can configure +different sets of plugins for different jobs or projects. + +B Use C to list all installed plugins. Read more +about each plugin in C. + +=head2 Note about (missing) Plugins + +Up to version 2.028 a lot of plugins where included in the main distribution +C. To make installation easier and faster, all non-core +command plugins have been moved into distinct, standalone distributions. + +The following plugins are affected: + +=over + +=item * App::TimeTracker::Git (which also includes SyncViaGit) + +=item * App::TimeTracker::RT + +=item * App::TimeTracker::TellRemote (which was called Post2IRC earlier) + +=item * App::TimeTracker::Overtime has been removed, while the idea is nice, the API and implementation are not good enough. + +=item * App::TimeTracker::TextNotify has been removed. + +=back + +=head1 SOURCE CODE + +=head2 git + +We use C<< git >> for version control and maintain a public repository on +L. + +You can find the latest version of L here: + +L + +If you want to work on L, add a feature, add a plugin or fix +a bug, please feel free to L the +repo and send us L +to merge your changes. + +To report a bug, please B use the C<< issues >> feature from github; +use RT instead. + +=head2 CPAN + +L is distributed via L, the +Comprehensive Perl Archive Network. Here are a few different views of +CPAN, offering slightly different features: + +=over + +=item * L + +=item * L + +=back + +=head1 Viewing and reporting Bugs + +We use L (thank you +L) for bug reporting. Please do +not use the C feature of github! We pay no attention to those... + +Please use this URL to view and report bugs: + +L + =head1 CONTRIBUTORS Maros Kollar, Klaus Ita, Yanick Champoux, Lukas Rampa, David Schmidt, Michael Kröll, Thomas Sibley, Nelo Onyiah, Jozef Kutej, Roland Lammel, Ruslan Zakirov, Kartik Thakore, Tokuhiro Matsuno, Paul Cochrane, David Provost, Mohammad S Anwar, Håkon Hægland -