App::TimelogTxt::Tutorial - Describe normal use of the
This tutorial applies to App::TimelogTxt version 0.12.
To use the
you need a directory where
timelog stores its log files.
This directory may be specified in the .timelogrc configuration file in your home directory.
If that file does not exist,
the program defaults to the timelog directory in your home directory.
You can use the init command to set up the configuration file and directory for you. If the default configuration is satisfactory, just run the following command:
$ timelog init
If you would like to change the directory where the logs are stored, supply that directory path as an argument to the init command.
$ timelog init ~/my_timelog
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 the ability to track more than one task at a time 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 @Email
Any 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 Meeting
The meeting is over and you need to change tasks. During 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 manual
We 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 questions
When all of Sue's questions are answered, you want to go back to the manual work.
$ timelog pop
The 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 module
You get some good uninterrupted time on this and finish up the module in time to stop at 5.
$ timelog stop
As 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.
The most detailed report you might do is to list all of the events 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 yesterday
The 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 stop
This is the most detailed report, but it isn't really useful for much. Usually, you want some form of summarized information. The other reporting commands take care of that.
The report I use the most looks like the following:
$ timelog report yesterday
This 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)
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 yesterday
This 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:55
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 yesterday
This just tells how long you were working. Sometimes it is all you need.
As you use the
timelog program more, typing long strings for individual events 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.
timelog program supports defining aliases in your .timelogrc file. These aliases can be either full events or partial events. 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 @Questions
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 events or partial events easily. To use an alias, use the alias as the command when calling
$ timelog email
This gets converted to
$ timelog start +Misc @Email
The proja alias above is a good example of a partial event. You would use the alias like:
$ timelog proja @ConfCall Client design team
which would be converted to
$ timelog start +ProjectA @ConfCall Client design team
Over time, I often find myself adding new aliases for events relating to new projects and deleting aliases that I no longer use.
G. Wade Johnson
Copyright (c) 2013, G. Wade Johnson
<email@example.com>. 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.