Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Move lib-related docs to main lib file #46

Merged
merged 4 commits into from
Nov 22, 2020
Merged

Move lib-related docs to main lib file #46

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
d4eafef
Move installation instructions into main lib file
paultcochrane Nov 19, 2020
1efabd0
Move SOURCE CODE and CPAN sections into main lib file
paultcochrane Nov 19, 2020
3a2f7c4
Move plugin-related docs to new PLUGINS section in main lib file
paultcochrane Nov 19, 2020
4465c82
Move USAGE docs higher in tracker docs
paultcochrane Nov 19, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
293 changes: 79 additions & 214 deletions bin/tracker
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -27,98 +27,6 @@ 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 command line.

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

=head2 Note about (missing) Plugins

Up to version 2.028 a lot of plugins where included in the main distribution
C<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:

=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<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

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

=head2 From a git checkout

Clone the repository if you have not already done so, and enter the
C<App-TimeTracker> directory:

~$ git clone git@github.com:domm/App-TimeTracker.git
~$ cd App-TimeTracker

C<App-TimeTracker> uses L<Dist::Zilla> to build, test and install the code,
hence this must be installed first, e.g. with C<cpanm>:

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

Now install the distribution's dependencies, test and install in the usual
manner for C<Dist::Zilla> 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<tracker>, it will create the directory
Expand All @@ -130,102 +38,6 @@ C<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.

=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
Expand Down Expand Up @@ -363,45 +175,98 @@ The filename of a C<tracking file> looks like
'YYYYMMDD-HHMMSS_$project.trc', for example:
F<20110811-090437_App_TimeTracker.trc>.

=head1 SOURCE CODE
=head1 CONFIGURATION

=head2 git
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>.

We use C<< git >> for version control and maintain a public repository on
L<github|http://github.com>.
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.

You can find the latest version of L<App::TimeTracker> here:
See L<App::TimeTracker::Command::Core> and the various plugins for valid config
parameters.

L<https://github.com/domm/App-TimeTracker>
=head2 The different config files

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.
=head3 Main config file: ~/.TimeTracker/tracker.json

To report a bug, please B<do not> 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<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.

=head2 CPAN
=head3 List of projects: ~/.TimeTracker/projects.json

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

=over
=head3 Per project config file: your-project/.tracker.json

=item * L<https://metacpan.org/release/App-TimeTracker/>
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<http://search.cpan.org/dist/App-TimeTracker/>
=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<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...
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.

Please use this URL to view and report bugs:
If you hit C<start> in F<~/job/>, only F<~/job/.tracker.json> and
C<~/.TimeTracker/tracker.json> will be used.

L<https://rt.cpan.org/Public/Dist/Display.html?Name=App-TimeTracker>
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'
],
Loading