NAME
App::TimelogTxt::Tutorial - Describe normal use of the timelog application.
VERSION
This tutorial applies to App::TimelogTxt version 0.04.
Example Usage
In this example, we will see most of the timelog commands you would use in a normal day. The start and stop commands are the minimum that you would need. To begin tracking a task, you use the start command and supply text to describe the task you are beginning. The timelog software assumes that you are only working a single thing at a time. I originally tried to support that ability and found that I never actually used it.
Let's walk through an example. Assume that it's just after lunch and you want to take care of your email before your team meeting at 1pm. At 10 minutes to 1, you start a task Email in the Admin project.
$ timelog start +Admin @EmailAny group of non-whitespace characters beginning with '+' is considered the project. If there is an string of non-whitespace characters beginning with '@', it is treated as the task. Any other text is explanatory details.
At 1pm, the conference call with your team is going to begin. You start that task. Since we are going to be talking about the Foo project, note that in the command.
$ timelog start +Foo @ConfCall Team MeetingDuring the meeting, you agreed to do some general work on the manual for the project's software. Enter the task to begin working on that.
$ timelog start +Foo @Docs working on manualWe are in the same project, so timelog will be able to report the cumulative total of the last two tasks. About 20 minutes after you start on the manual, Sue comes by to ask about the project you were working on last week. Since this is will be a temporary interruption, we use the push command. It saves the current task, so that we can restore it when the interruption is over.
$ timelog push +Bar @Help Sue questionsWhen Sue is satisfied, you want to go back to the manual work.
$ timelog popThe pop command restores the task that was current when the last push command was executed. This way you don't need to type in the whole command (or up-arrow through your command history), for short interruptions.
A while later, you've finished with the manual for today and want to finish up the work on the database module for the Foo project.
$ timelog start +Foo @Code database moduleYou get some good uninterrupted time on this and finish up the module in time to stop at 5.
$ timelog stopAs you can see, this requires the addition of a bit more to your daily work flow. Later in the manual we will cover a few features that can reduce your typing. The main benefit of all of this work though is the ability to generate reports of your work.
Reports
The most detailed report you might do is to list all of the entries for a given day. If you executed the following command the day after the example above, you would get a list of the tasks for that day.
$ timelog ls yesterdayThe output of this command (assuming only the commands from the example) would look like this:
2013-07-01 12:50:02 +Admin @Email
2013-07-01 13:00:21 +Foo @ConfCall Team Meeting
2013-07-01 14:02:43 +Foo @Docs working on manual
2013-07-01 14:22:03 +Bar @Help Sue questions
2013-07-01 14:27:06 +Foo @Docs working on manual
2013-07-01 15:10:20 +Foo @Code database module
2013-07-01 17:00:24 stopThis is the most detailed report, but it isn't really useful for much. Usually, you want some form of summarize information. The other reporting commands take care of that.
Detail Report
The report I use the most looks like the following:
$ timelog report yesterdayThis report shows the data for the given date grouped by project. Although the actual times are missing and the data is re-ordered, you can get a really good sense of where your time went with this report.
2013-07-01 4:10
Admin 0:10
Email 0:10
Bar 0:05
Help 0:05 (Sue questions)
Foo 3:55
Code 1:50 (database module)
Docs 1:03 (working on manual)
ConfCall 1:02 (Team Meeting)Summary Report
Sometimes, the normal report is still too much data. Let's say I only care about the aggregate amount of time spent on each project. I would then use the following command:
$ timelog summary yesterdayThis report has no task information, it just reports the time on each project for the day.
2013-07-01 4:10
Admin 0:10
Bar 0:05
Foo 3:55Hours Report
Finally, you may only want the amount of time you spent for the whole day. That report is generated by the following command:
$ timelog hours yesterdayThis just tells how long you were working. Sometimes it is all you need.
2013-07-01 4:10Simplifying Usage with Aliases
As you use the timelog program more, typing long strings for individual tasks becomes annoying. If you are working on the same projects or tasks on a regular basis, you might find typing the detail annoying even if you want it for reporting.
The timelog program supports defining aliases in your .timelogrc file. These aliases can be either full commands or partial commands. These aliases are defined in a [alias] section in your .timelogrc file. They take the following form:
email = start +Misc @Email
proja = start +ProjectA
int = push +Misc @QuestionsWhen timelog encounters an alias at the beginning of its command line, it replaces the alias with the string after the equals. This allows you to define full commands or partial commands easily. To use an alias, use the alias as the command when calling timelog:
$ timelog emailThis gets converted to
$ timelog start +Misc @EmailThe proja alias above is a good example of a partial command. You would use it like:
$ timelog proja @ConfCall Client design teamwhich would be converted to
$ timelog start +ProjectA @ConfCall Client design teamOver time, I often find myself adding new aliases for tasks relating to new projects and deleting aliases that I no longer use.
AUTHOR
G. Wade Johnson <gwadej@cpan.org>
LICENCE AND COPYRIGHT
Copyright (c) 2013, G. Wade Johnson <gwadej@cpan.org>. All rights reserved.
This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See perlartistic.