Introduction
The rtimelog
program is a time-tracking and reporting system that has grown over several years to
meet my needs. It’s main features are a simple log file format and a straight-forward command line
tool.
Unlike many time-trackers, rtimelog
focuses on entering tasks easily and simple reporting, rather
than fancy GUI interfaces. The idea is that in a fancier tracking tool, you are more likely to spend
time using the tool to track time rather than getting work accomplished. Moreover, I am quite
comfortable working with a command line, that’s all I focused on.
Conventions
Since this is a command line tool, most of the examples show running the program in a shell. The
code that you would type in the command line will be in a block and preceded by a $
character. Any
lines shown without the $
in the same block are the response from the program.
This is a command without any response.
$ rtimelog start +project @Code
This is a command with a response.
$ rtimelog curr
+project @Code
Using rtimelog
To use rtimelog
, you will need to install the program and do at least minimal configuration.
The tool supports some customization that you can use to simplify your use of the program and make
it more efficient for how you need to track time.
Getting Started
When you are getting started using rtimelog
, there are a couple of steps that you will do once and
then never again: installing the program and initializing it.
Installation
Since rtimelog
is written in Rust, the easiest way to install it is from
crates.io using the cargo
application. If you have cargo
installed, type
the following on the command line.
$ cargo install rtimelog
If you are interested in checking out the source of the tool, you can get the latest version from
the gitlab repo. You will still need to build a Rust
executable to make use of rtimelog
.
Initialization
The rtimelog
program requires a directory where it 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:
$ rtimelog 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.
$ rtimelog init ~/my_timelog
For more information about configuring the program, check out the configuration section of the Manual.
A Day in the Life
In this example, we will see most of the rtimelog
commands you would use in a normal day. The
start
and stop
commands are the minimum that you would need, but we will go a bit further.
To begin tracking a task, you use the start
command and supply text to describe the task you are
beginning. The rtimelog
program 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. While walking this example, you will probably find the amount of
typing to be a bit much. The rtimelog
program supports features to reduce the amount of typing.
The Customized Day example shows how I would have customized my configuration
for this work. It doesn’t have all of the explanation, so you might want to go there next.
Morning
You’ve just started your day and decide to clear your email before focusing on coding. As soon as you’ve logged in, you start a task named Email in the Admin project.
A project like Admin is useful for administrative tasks that don’t necessarily fit into an actual project. That pseudo-project helps track little tasks that can consume too much of your day if you aren’t paying attention.
A task is made up of several optional parts (at least one of which must be there):
- a project (first group of non-whitespace characters beginning with ‘
+
’) - a task name (first group of non-whitepsace characters beginning with ‘
@
’) - explanatory details for the task
$ rtimelog start +Admin @Email
One design decision for rtimelog
is that it only tracks one task at a time. Whatever task you are
working on is stopped when you start a new one.
After you finish clearing email, you decide to take advantage of the morning quiet and dig into the work on the processing module for the Foo project. This is a fairly intense chunk of work, so you want to take it on when you have time.
$ rtimelog start +Foo @Code processing module
We’re going to call this task @Code despite the fact that you will be doing design and writing unit tests while you work on the code. Those kinds of work can all be collected under Code to avoid wasting time with unnecessarily detailed task tracking.
After about an hour and a half, you are pretty comfortable with the changes to the processing
module. But, you decide to test the impact of the new code on the performance of the system, so you
decide to do a little performance measuring. Since this is a little diversion and you plan to come
back to coding when you finish, you decide to push
the old task onto the stack while starting a
new task. This will simplify returning to the coding task when you are ready.
The push
command performs two actions. First, it pushes your current task only the stack so that
you can resume it later. Then, it starts the new task that you provided to push
.
$ rtimelog push +Foo @PerfTest processing module
We are in the same project, so rtimelog
will be able to report the cumulative total of the last
two tasks when generating a report. Since we plan to come right back to coding after the test, let’s
use push
instead of start
to temporarily move to a new task.
After half an hour, you’ve identified some performance bottlenecks and return to coding in order to
fix what you’ve found. So, let’s resume
the coding work. Since it’s been half an hour, you might
want to confirm that you are resuming what you thought you were working on, so use the stack top
command to see what it on the top of the stack.
$ rtimelog stack top
+Foo @Code processing module
Since the last item is code work, let’s resume
.
$ rtimelog resume
The resume
command restores the task that was current when the last push
or pause
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. Since we pushed the previous task, the resume
command is
equivalent to re-typing the original command: start +Foo @Code processing module
.
When you finish tidying up the performance work, you decide to move on to the database module. Since
this is not a temporary diversion, you will use start
again.
$ rtimelog start +Foo @Code database module
As noon rolls around, it’s time to take a break for lunch. We can use pause
to stop what we are
doing after pushing the current task on the stack to resume later.
$ rtimelog pause
Afternoon
When you get back from lunch, you decide to take care of any morning email before your team meeting
at 1pm. You start the +Admin @Email
task again.
$ rtimelog start +Admin @Email
Wouldn’t it be nice to start common tasks with less typing? We’ll revisit this in the next chapter.
At 1pm, the conference call with your team begins. You start that task. Since we are going to be
talking about the Foo
project, make sure to set the project name appropriately.
$ rtimelog start +Foo @ConfCall Team Meeting
When the meeting is over, 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.
$ rtimelog start +Foo @Docs working on manual
About 20 minutes after you start on the manual, Emma comes by to ask about the project you worked on
last week. Since this is will be a temporary interruption, we use the push
command. Once again,
this will make it easier to restore our task when the interruption is over.
$ rtimelog push +Bar @Help Emma questions
Interruptions for questions are a great use case for push
. You want to be able to resume
right
back into your current task when you are finished.
When all of Emma’s questions are answered, you go back to the manual work using the resume
command.
$ rtimelog resume
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. Since you pause
d for lunch, you can once again use resume
to pick up where you left off.
Even though this diversion was hours ago, rtimelog
still remembers that you push
ed a task. This
allows you to resume
to restore the previous task.
Once again, you’ll probably want to check the top of the stack to confirm you didn’t have anything else waiting.
$ rtimelog stack top
+Foo @Code database module
Since the database work was the last thing you paused, go ahead and resume
.
$ rtimelog resume
You get some good uninterrupted time on this and finish up the module in time to stop at 5.
$ rtimelog stop
Conclusion
Obviously, using rtimelog
adds a little bit of overhead to your daily work. This example doesn’t
make use of aliases which can reduce typing dramatically. The Customized
Day example shows these features in action.
Once you get used to it (and customize the aliases for your work), you will likely find that the overhead is not a big as it seems. The goal of the tool is to provide some benefits to make this extra work worthwhile. That benefit is the ability to see and understand where you spend time during the day through reports of your work.
Customized Day
The Day in the Life example uses rtimelog
without any customization to
introduce the features of the program and show the details tracking tasks.
The reality is that many of the tasks you will want to track are repeated either in full or in part every day, or multiple times during the day. The Aliasing feature allows you to customize the command line more to your way of working.
How I Would Customize
Shortening the Command Name
The name of the program is too long for me to type multiple times a day. So, I use a shell alias to make it shorter. In the bash shell, that would be:
alias tl=~/.cargo/bin/rtimelog
Most command line shells support the ability to alias
a command with a string of your choosing. I
often use this feature to shorten commands I type a lot. For example, I have single character
aliases for my editor and for git
.
This allows me to use tl
on the command line instead of typing 8 characters. I have added this
alias to my .bashrc
file to make the alias always available.
Using rtimelog
Aliases
My ~/.timelogrc
configuration file would contain an [alias]
section with shorter commands for
common tasks. For the example, I’d have probably added at least the following:
[alias]
email = start +Admin @Email
foo = start +Foo
pfoo = push +Foo
foocode = start +Foo @Code
foodocs = start +Foo @Docs
foomtg = start +Foo @ConfCall Team Meeting
barhelp = push +Bar @Help
Quicker Workday
The following sections are a shortened version of the example from the previous chapter. The text is
a shortened form of the description. More importantly, it uses aliases to reduce the typing for the
rtimelog
commands.
The aliases reduce my task typing to the following:
Morning
Starting the day with email.
$ tl email
Start on processing module for Foo.
$ tl foocode processing module
After about an hour and a half, you are pretty comfortable with the changes to the processing module. Make a detour into performance testing
$ tl pfoo @PerfTest processing module
After half an hour, you’ve identified some performance bottlenecks and return to coding in order to fix what you’ve found. Quick check to verify what’s on top of the stack.
$ tl stack top
+Foo @Code processing module
Let’s resume
the coding work.
$ tl resume
When you finish tidying up the performance work, you decide to move on to the database module. Since
this is not a temporary diversion, you will use start
again.
$ tl foocode database module
As noon rolls around, it’s time to take a break for lunch. We can use pause
to stop what we are
doing after pushing the current task on the stack to resume later.
$ tl pause
Afternoon
When you get back from lunch, you decide to take care of any morning email before your team meeting
at 1pm. You start the email
task again.
$ tl email
At 1pm, the conference call with your team begins. You start that task. Since we are going to be
talking about the Foo
project, make sure to set the project name appropriately.
$ tl foomtg
When the meeting is over, 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.
$ tl foodocs working on manual
About 20 minutes after you start on the manual, Emma comes by to ask about the project you worked on
last week. Since this is will be a temporary interruption, we use the push
command. Once again,
this will make it easier to restore our task when the interruption is over.
$ tl barhelp Emma questions
When all of Emma’s questions are answered, you go back to the manual work using the resume
command.
$ tl resume
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. Since you pause
d for lunch, you can once again use resume
to pick up where you left off.
Once again, you’ll probably want to check the top of the stack to confirm you didn’t have anything else waiting.
$ tl stack top
+Foo @Code database module
Resume the database work.
$ tl resume
You get some good uninterrupted time on this and finish up the module in time to stop at 5.
$ tl stop
Conclusion
Using a shorter name for the command and aliasing common tasks make use of rtimelog
more efficient
to use. The most important thing to keep in mind for your aliases is to pick what works well for
you. There are probably tasks you will do a dozen times a week that I can’t imagine. Customize the
aliases to make your work easier.
Events
In addition to timing tasks, rtimelog
can be used to track events that don’t have a useful
duration. These zero duration events are added to the timelog with the event
command. The
command tasks a description of the event. For example,
$ rtimelog event +dog @Walk Evening
The event description follows the same form as a task. The first group of non-whitespace characters
beginning with ‘+
’ after the start
command is considered the project. You can think of the
project in this case as being more of a group of events. If there is a string of non-whitespace
characters beginning with ‘@
’, it is treated as the event name. Any other text is explanatory
details for the event.
See the Event Reports section for the kinds of reports supported by
rtimelog
.
Reporting
Time tracking would not be particularly useful without some way to report on the time you are
tracking. The rtimelog
program has a number of reports, each serving a different purpose.
Detail Report
The report I use the most looks like the following:
$ rtimelog report detail 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 8:08
Admin 0:19
Email 0:19
Bar 0:05
Help 0:05 (Emma questions)
Foo 7:45
Code 2:20 (database module)
Code 2:50 (processing module)
ConfCall 1:02 (Team Meeting)
Docs 1:03 (working on manual)
PerfTest 0:30 (processing module)
From this report, we can see that the part of the day we tracked was 8 hours and 8 minutes. Almost
all of that was spent on the Foo
project, on five separate tasks:
- Code work on the database module
- Code work on the processing module
- Performance testing on the processing module
- Documentation on the manual
- Team conference call
We also spent some incidental time on email and answering questions.
Where this report really shines are those days that seems to be one interrupt after another. That was really the origin of the program for me. I found that there were days when I left work tired, but didn’t feel like I had accomplished anything. Looking back at this report showed the day taken up by dozens of interruptions.
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:
$ rtimelog report summary yesterday
This report has no task information, it just reports the time on each project for the day.
2013-07-01 8:08
Admin 0:19
Bar 0:05
Foo 7:45
If you only work on one project at a time, this report will not be very useful. However, I have found this report handy for as few as two projects. For example, handing off one project to another team, while beginning a new project. During the beginning of the hand-off, there are usually a number of meetings and interruptions helping the other team take over. It’s not always easy to realize how much time is spent on this kind of activity.
This report is most useful for people who need to track multiple projects every day. If you use the Admin pseudo-project described earlier, this can still be useful for recognizing how much time you are spending on non-project tasks. Those kinds of time-stealers are easy to lose track of.
Hours Report
Finally, you may only want the amount of time you spent for the whole day. That report is generated by the following command:
$ rtimelog report hours yesterday
This just tells how long you were working. Sometimes, it is all you need.
2013-07-01 8:08
This report is particularly useful when you are looking at multiple days. Sometime just a report of the amount of time you have spent each day of the week is useful.
Chart
The report chart
command gives a graphical representation of the time spent during the day as an
HTML page. The data is displayed as a pie chart breaking down the projects worked during the day.
For each project, there is a smaller pie chart for the tasks applied to that project.
Finally, there is a hourly bar chart showing the time in each hour spent on the various projects. The chart report for the example shows the output of this command.
I created this report specifically as an exercise after seeing some of the output from other time tracking programs. Although I use it relatively rarely, someone who is more visually-oriented might find this version more useful.
This report was a result of someone showing really pretty charts from a fancy time-tracking app. I have usually resisted adding features that I don’t see myself using a lot. But, I built this mostly to show how much this simple tool could do. I still don’t use it much.
Task Listing
The most detailed report you might run 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 entries for that day.
$ rtimelog ls yesterday
The output of this command (assuming only the commands from Example Usage) would look like this:
2013-07-01 08:02:15 +Admin @Email
2013-07-01 08:10:31 +Foo @Code processing module
2013-07-01 09:30:42 +Foo @PerfTest processing module
2013-07-01 10:00:38 +Foo @Code processing module
2013-07-01 11:30:22 +Foo @Code database module
2013-07-01 12:00:11 stop
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 Emma 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.
Event Reports
If you are using the zero duration events feature of rtimelog
, you might want to generate reports
for those.
The report events
command lists your events and the time that they were added grouped by date.
$ rtimelog report events -p dog yesterday today
If you used events to track letting the dog out, the command could give a report of
2022-12-15
07:50 +dog Backyard
14:22 +dog Backyard
18:33 +dog Walk
2022-12-16
08:10 +dog Backyard
14:32 +dog Backyard
18:27 +dog Walk
This report is much like the ls
report for tasks. No summary or calculations, just a list of the
events.
The report intervals
command lists the interval between events. So if you track replacing a
battery in an outdoor camera, knowing the time since the last change would be useful.
$ rtimelog report intervals -p camera october today
The above command might report
2022-10-07 19:20 +camera Battery : 29d 12:03
2022-11-06 07:23 +camera Battery : 26d 11:03
2022-12-02 18:27 +camera Battery : 20d 23:51
This shows that we’ll want to check the battery about a week from now.
The intervals
report gives the time interval between event
s. This actually gives some useful
information.
Correcting Entries
There are many reasons why you might not enter an entry exactly correctly:
- you mistype the details on a task entry
- you realize that a quick interruption is taking a significant amount of time
- you begin a task entry for a meeting and find it has been delayed
- you start a task entry for a meeting, only to discover it has been canceled
- you start working on a new task and then realize that you forgot to enter it
The most general tool for this job is the edit
command. This command opens the timelog file in
your configured editor and allows you to make any changes. Including editing the text of the task,
changing the start time, re-arranging entries or deleting entries.
In many cases, the edit
command is too big a hammer for a quick change. The rtimelog
program
supports a few more targeted commands for manipulating the last task.
If we were perfect, there would be no need for these commands. The edit
command and the more
targetted editing commands are designed to simpify fixing our mistakes. The following sections are
focused on fixing particular mistakes.
What if you start a task and decide you won’t do it?
Maybe you start a task for a meeting and it gets cancelled. You can use
$ rtimelog entry discard
to throw that entry away. If you want to keep a record of the meeting start but not count it in your time reports, you can use the following instead.
$ rtimelog entry ignore
This command keeps the face that the task was entered, but marks that task as invisible to time tracking.
You accidentally start the task too soon.
I sometimes start the task entry and realize that the activity has not started yet. (Maybe starting a couple of minutes before the meeting actually starts.)
$ rtimelog entry now
This resets the entry to right now.
You realize that you are working on an activity and did not add an entry.
This happens more than I would like to admit. So, I immediately add a new entry. Then I will want to
adjust the time. If I only should have started a few minutes ago, the rewind
command allows me to
move back a number of minutes.
$ rtimelog entry rewind 5
On the other hand, if I know the exact time I should have started the task, I would use the was
command instead.
$ rtimelog entry was 9:00
You realize that you forgot to enter a task as you are starting a new one.
I find that forgetting to start a short task is not an unusual occurrence. Unfortunately, I often
realize this as I’m starting a new task. The brute force was to handle this would be to add both
tasks and then use edit
to fix the times afterward.
$ rtimelog start +Foo @Questions Answer John
$ rtimelog start +Foo @Admin Create card for reported bug
$ rtimelog edit
While in the editor, I can now correct the first time entry (maybe setting the time back for the 5 minutes I spent answering John).
You realize that you forgot to enter the previous task as you are starting a new one.
A variation on the previous question would be starting a task and while working on it realize that I forgot to enter the previous one. Let’s say I want to make a card for a bug reported by John.
$ rtimelog start +Foo @Admin Create card for reported bug
As I finish up that card, I realize that I actually spent 5 minutes talking with John about the issue before creating the card.
$ rtimelog start +Foo @Questions Answer John
$ rtimelog edit
Unlike the last time, these events are now out of order. So, in the editor, I’d swap the last two entries and then fix the time for the (now) second-to-last item.
I mistyped the task description when creating an event.
Just as I hit enter
while entering a task, I realize that I have misspelled the project name.
$ rtimelog start +F00 @COde charting code
Obviously, I typed +F00
instead of +Foo
, and I also capitalized the O
in Code
. As a quick
fix, I can type:
$ rtimelog entry rewrite +Foo @Code charting code
This doesn’t change the time, it only rewrites everything from the project to the end of the line.
Temporary Tasks and the Stack
You may find yourself needing to temporarily pause your current task to work on another, with the
intent to come right back. This kind of interrupt happens so commonly, that I added functionality to
the timelog
system early on to deal with it.
The concept of a stack is fairly well-known to developers, but may not be as comfortable to
non-developers. A stack makes it easy to deal with temporarily saving something and restoring it
later. The useful property of a stack is that you can push
multiple things on a stack and then
easily remove them in the opposite order. This is known as a “last in, first out” process.
Stack Usage
The push
command saves the current task to the stack, and changes to supplied task.
$ rtimelog curr
2023-10-24 20:10 +projA @Code
Duration: 1:23
$ rtimelog stack top
$ rtimelog push +projA @Meeting
$ rtimelog curr
2023-10-24 21:33 +projA @Meeting
Duration: 0:00
$ rtimelog stack top
+projA @Code
When you are ready to come back to the previous task, you use the resume
command.
$ rtimelog resume
$ rtimelog curr
2023-10-24 21:40 +projA @Code
Duration: 0:00
$ rtimelog stack top
When you find yourself toggling between two tasks for some reason, the swap
command uses the stack
in a more advanced way.
Assuming we start work on the Foo project.
$ rtimelog start +Foo @Monitor
$ rtimelog curr
+Foo @Monitor
$ rtimelog stack top
Later, we want to push the Bar project.
$ rtimelog push +Bar @Monitor
$ rtimelog curr
2023-10-24 21:53 +Bar @Monitor
Duration: 0:00
$ rtimelog stack top
+Foo @Monitor
Next, we want to go back the Foo project, knowing that we will come back to Bar shortly. We can
use swap
for that, and we’ll use the tools to see the log and the stack.
$ rtimelog swap
$ rtimelog curr
2023-10-24 21:54 +Bar @Monitor
Duration: 0:00
$ rtimelog stack top
+Foo @Monitor
Notice that Foo and Bar have swapped places.
Stack Reporting
To see the task descriptions on the stack, use the stack ls
.
$ rtimelog stack ls
If you just want to know the top item on the stack, use stack top
.
$ rtimelog stack top
Stack Maintenance
If you use the stack a great deal, you may find that it begins to grow out of hand. You’ll probably decide that some of the items on the stack are no longer useful and can be discarded. The following commands support manipulation of the stack.
If you want to discard task descriptions from the top of the stack, use the stack drop
command.
$ rtimelog stack drop
To discard everything on the stack, use stack clear
.
$ rtimelog stack clear
If the most recent task descriptions might still be useful, but the older items could be removed,
you can use the stack keep
.
$ rtimelog stack keep
Reducing Typing with Aliases
As you use the rtimelog
program more, typing long strings for individual entries 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.
Aliases started out as a really simple text replacement to allow shortening command typing.
Slightly more advanced replacement text is now supported with the idea of trying to reduce the number of aliases.
Defining Aliases
The rtimelog
program supports defining aliases in your .timelogrc
file. These aliases can be
either full events or partial events. The aliases are defined in a [alias] section in your
.timelogrc
file. They take the following form:
[alias]
email = start +Misc @Email
proja = start +ProjectA
int = push +Misc @Questions
When rtimelog
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 rtimelog
:
$ rtimelog email
This gets converted to
$ rtimelog start +Misc @Email
The proja alias above is a good example of a partial event. You would use the alias like:
$ rtimelog proja @ConfCall Client design team
This is equivalent to typing
$ rtimelog start +ProjectA @ConfCall Client design team
Alias Templates
Over time, I often find myself adding new aliases for events relating to new projects and deleting aliases that I no longer use. After a while, I noticed that I tended to make clusters of aliases for particular projects. All of the extra alias maintenance seemed ridiculous. What I really needed was a way to make aliases that were templates, rather than just replacement strings.
If the expansion string for an alias contains the string {}
, it is handled a bit differently. For
example, if we assume the following aliases:
email = start +Misc @Email
code = start +client:{} @Code
doc = start +client:{} @Doc
test = start +client:{} @Test
rtimelog
replaces the {}
with the argument that comes after the alias. So
using the code alias as follows:
$ rtimelog code Bob New UI
is equivalent to typing
$ rtimelog start +client:Bob @Code New UI
This expansion continues until all {}
strings are replaced. If we try to replace a {}
and there
is no corresponding argument, the {}
will be left in place. This has dramatically improved the
entry detail I use without requiring nearly as much maintenance of my aliases.