Introduction

For reasons explained in the History appendix, I found the need years ago to build a simple tool for tracking my time. The format of the timelog file and some of the functionality was inspired by Gina Trapani’s Todo.txt program. It’s main feature is the simplicity of its file format:

• One entry per line
• pure text
• minimal formatting

For details of the file format, see the Format appendix.

Installation

Since rtimelog was 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.

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

rtimelog Command

The rtimelog program manipulates your time log and generates reports. The program is executed with a command and optional arguments. The individual commands are described in upcoming chapters but for the sake of completeness, this describes an initial workflow. For a more extensive example, see the tutorial.

Initialize Default Configuration

Before using rtimelog, you need to set up the initial configuration. You’ll need to run the following command once.

  $ rtimelog init

The init command sets up the initial configuration file and the directory for the timelog files. Further information about customizing your configuration is described in the Configuration Chapter.

Simple Task Creation

Adding a task entry to the time log is easy with the start command.

$ rtimelog start +project @Task Details

Adding a new task entry closes any open task and starts the new one.

Finishing Tasks

To stop the current task without starting a new one (for instance at the end of the day) is handled by the stop command.

$ rtimelog stop

See the Supported Commands chapter for more commands.

String Arguments

Many timelog commands require specially formatted strings as arguments. Since these kinds of arguments are critical to using rtimelog, let’s go over these formats first.

• Dates and Ranges
• Task Descriptor
• Event Descriptor

Dates and Ranges

Commands that report on the data in the timelog need a way of specifying either a date or range of dates for the report. By default, these reports cover the current day. The date range descriptor supports specifying different dates or ranges of dates. For convenience, these descriptors can take on several forms.

Single Date

A single date is specified in one of the following forms:

• explicit date of the form yyyy-mm-dd
• the string today
• the string yesterday
• a day of the week: sunday, monday, tuesday, wednesday, … etc.

The values of today and yesterday describe the appropriate expected day. Each of the weekday values references the last instance of that day before today.

Any of these single dates results in a range spanning one day.

Date Pair

A pair of dates in one the forms above.

This pair results in a range that covers the two supplied dates. If the dates are in order, the start is the first date and end is the second date. If the dates are out of order, the range is not valid.

The two dates are not required to be in the same form. So, the following ranges are legal (assuming a current date of 2023-10-30):

Range Description

A range description in one of the following forms:

• a month name: january, february, march, … etc.
• a short (3 char) month name: jan, feb, mar, … etc.
• a relative time frame: (this|last) (week|month|year)
• the string ytd

If the range description is a month name, the range will cover the whole month with that name before today. If we are in the month of June, a value of may will refer to the previous month, but a value of july will refer to last year’s July.

If the range description is this followed by week, month, or year, the resultant range covers:

• this week: from the last Sunday to Saturday of this week,
• this month: from the first day of the current month to last day of the month,
• this year: from the January 1 of the current year to the last day of the year.

If the range description is last followed by week, month, or year, the resultant range covers:

• last week: from the two Sundays ago to last Saturday,
• last month: from the first of the month before this one to the last day of that month,
• last year: from January 1 of the year before the current one to December 31 of the same year.

If the range description is the string ytd, the range will be from January 1 of the current year up to today.

Task Description

A task description is a text string that may have a +project and/or a @taskname.

Project

The first string of non-whitespace characters beginning with a ‘+’ is treated as the project for this entry. The project is useful for grouping tasks and is relevant when using the reporting commands.

The obvious use for projects would be actual business projects. Any way of grouping tasks that works for you is useful.

Task Name

Additionally, the first string of non-whitespace characters beginning with a ‘@’ is treated as a task name. Task names are often general task types. For a developer, possibles might include: @Code, @Test, @Docs, @CodeReview, @Deploy, etc.

Obviously, the task names are also very personal. So, use whatever works best for you. I also find myself using special purpose task names, that might never (or rarely) be used again.

Task Details

If a task has no name, the non-project part of the entry is treated as the task name. Otherwise, the non-project, non-taskname part of the event is treated as detail information for the event.

Event Descriptor

The argument to the event command is a description of the event. The first string of non-whitespace characters beginning with a ‘+’ is treated as the project or event group. This is useful for grouping related sets of events.

The project in events also seem not at all like the kinds of task projects. Grouping similar events by a term like has been useful.

Supported Commands

The rtimelog program supports a number of commands that manipulate or report on the time logged by the program. To make the commands a little easier to understand, they are grouped by related functionality.

The only commands required for using rtimelog are in the chapters Starting Tasks and Reporting. All of the other commands provide more functionality, but are not strictly required.

• Starting Tasks
• Adding Non-Task Entries
• Entry Manipulation Commands
• Stack Manipulation
• Informational Commands
• Reporting
• Other Commands

Starting Tasks

The commands you will use the most involve adding events to the time log.

Start a New Task

  $ rtimelog start +projA @Code Details

Start timing a new task, stopping any current task. Since rtimelog only tracks one task at a time, the current task is always stopped when starting a new task. The argument for this command is a Task Description.

Stop the Current Task

  $ rtimelog stop

Stop timing the current task.

Save the Current Task and Start Another

  $ rtimelog push +projA @Docs README

Save the current task description on the stack and start timing new task. The current task description is saved in the stack file in the timelog directory. The argument to this command is a Task Description.

You can manipulate the saved task description with resume, or one of the stack sub-commands.

Resume a Saved Command

  $ rtimelog resume

Stop the current task and restart top task from the stack. This also removes the task description from the stack.

Save the Current Task and Stop

  $ rtimelog pause

Save the current task description on the stack and stop that task from timing. It’s the equivalent of pushing the current task, while stopping timing at the same time.

Toggle Between Current and Saved Command

  $ rtimelog swap

Pop the top task description off the stack, resuming that task. Save the current task description on the stack. This is useful for time-slicing or toggling between a couple of activities.

Adding Non-Task Entries

Over time, I found a need for a few non-task related entries that would be useful to track along with the tasks. These commands allow adding those entries.

Add a Comment to Log

  $ rtimelog comment Beginning of new project

Add a comment line to the logfile. The argument to this command is the text of the comment. This text does not have any special format. It’s just the text of the comment.

Add a Zero Duration Event

  $ rtimelog event +pet @Walk

Add a zero duration event to the logfile. Denotes an event that has occurred and you would like to track, but which is not the beginning of a timed task. The argument to this command is the Event Description.

Entry Manipulation Commands

The entry command has subcommands to perform different actions on the most recent task entry in the logfile. In the past, I often found the need to execute the edit command to make small alterations to the most recent entry.

These sub-commands cover many of those small edits, without the big hammer of edit.

Removing Events

Discard an Entry

  $ rtimelog entry discard

Discard the most recent entry from the logfile. This is useful if you started a new task without meaning to or if the task you have just started has become irrelevant.

This removes the most recent task, continuing the timing of the interrupted task.

Ignore an Entry

  $ rtimelog entry ignore

Mark the most recent entry in the logfile as ignored. This is similar to discarding the new entry, but leaves an indication that the task was nearly started. The ignored entry does not contribute to reports in any way.

A good use for the entry ignore command is to show that you were interrupted from your current task, but spent no time away. For example, a meeting was supposed to start at 1pm. You mark the time, just as you get a message that the meeting was cancelled. You haven’t really spent any time on the meeting, but it might be useful to track the interruption.

This causes the timing of the interrupted task to continue.

Modify Entries

I find that most of the time I use the edit command to adjust the time of the most recent entry.

Quite often I start typing the command a bit before a meeting begins or something and then miss pressing enter. Other times I would start to answer a question for someone and then realize that this was going to be a long exercise, not a quick question. These commands allow for quickly adjusting the time.

Other issues that need editing are misspellings, that just require a quick adjustment.

Reset Command to Now

  $ rtimelog entry now

Reset the time of the most recent entry to now. This can be useful if you started a new task a little too soon.

Reset Task Time

  $ rtimelog entry was 10:23

Reset the time on the most recent entry. The argument for this command is a time formatted as either hh:mm or hh:mm:ss. The program will allow you to set the time whenever you want. If you set it before the previous entry time, it can cause difficulties generating reports.

Move Task Time Back

  $ rtimelog entry rewind 10

Shift the time on the most recent entry back the specified number of minutes. The program will allow you to push the most recent entry back as far back as you want. If you set it before the previous entry time, it can cause difficulties generating reports.

Replace Task Description

  $ rtimelog entry rewrite +right_project @NewTask Details

Replace the task description on the most recent entry. The argument for this command is a Task Description. This completely replaces the previous task description.

Stack Manipulation

In a given day, I find that much time is spent with meetings or quick questions that interrupt the main flow of my work. I will often need to move back to a previous task after the interruption. This lead to the addition of stack manipulation commands. These are purely for the purpose of reducing typing in certain circumstances and are not actually required for normal use of the program.

The stack command has sub-commands to perform different actions on the stack file. Those sub-commands are:

Display the Stack

  $ rtimelog stack ls

Display items on the stack. The top task description on the stack is the one that is restarted by the resume command.

Display Top of Stack

  $ rtimelog stack top

Display just the top item on the stack. This is the item that would have been restarted by the resume command.

Empty the Stack

  $ rtimelog stack clear

Clear the stack file, erasing everything from the stack.

Drop Items from Top of Stack

  $ rtimelog stack drop 3

Drop one or more task descriptions from top of entry stack. If no arguments are supplied, only the top item is dropped. If the argument is a number, that number of task descriptions is dropped from the stack.

Drop Items from Bottom of Stack

  $ rtimelog stack keep 5

Remove all task descriptions from the stack except the top {n} items. If no arguments are supplied, keep the top 10 items from the stack. If the supplied argument is a positive integer, all stack items except the n topmost are discarded.

Informational Commands

There are a number of commands that display some information from the timelog file. None of these commands change the log, they just display information.

List Entries

  $ rtimelog ls 2023-10-24

List entries for the specified day. See the Single Date format section that follows for information about date formats. Default to today.

List Projects

  $ rtimelog lsproj

List known projects, one per line.

Display Current Task and Duration

  $ rtimelog curr

Display the start date and time and task description of the current task, if any. It also displays the duration of the current task.

Reporting

The reporting commands generate a report of information from the timelog file. Many of these commands accept a date range descriptor. This descriptor specifies either a date or range of dates to include in the report. If no descriptor is supplied, the default is today.

Report Types

The report commands (except for chart) also support a repeatable option of -p which specifies a project to include in the report. The argument supplied with the -p option can either be the project name or part of a project name.

The reporting commands are:

• Time Reports
  • Detail Report
  • Summary Report
  • Hours Report
  • Task Chart
• Zero Duration Event Reports
  • Events Report
  • Intervals Report

Detail Report

The detail report organizes the data from the specified range of dates into a form that provides the maximum amount of summary data.

The -p option can be supplied 0 or more times to specify the projects shown in the report. If no -p is supplied, all projects are shown.

The optional date range descriptor specifies the dates covered by the report.

Output

The report for an example day might be:

  $ rtimelog report detail yesterday
  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)

This report is grouped by day, with each project grouped under the day. Each event for a project is displayed under the project. Accumulated times are displayed for each project and day. The default date range is today.

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

The summary report displays the amount of time spent on individual projects without dipping into the tasks for each project.

The -p option can be supplied 0 or more times to specify the projects shown in the report. If no -p is supplied, all projects are shown.

The optional date range descriptor specifies the dates covered by the report.

Output

The report for an example day might be:

  $ rtimelog report summary yesterday
  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

The hours report displays the hours worked for each of the requested days.

The -p option can be supplied 0 or more times to specify the projects shown in the report. If no -p is supplied, all projects are shown.

The optional date range descriptor specifies the dates covered by the report.

Output

The report for an example day might be:

  $ rtimelog report hours yesterday
  2013-07-01  8:08

Each day is reported on a separate line. Although pretty minimal, this report can be useful for some situations.

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.

Task Chart

Create a graphical dashboard containing pie charts showing the proportion of projects during the day, and tasks for each project, as well as bar graph showing how time during the day is distributed into projects.

The optional date range descriptor specifies the dates covered by the report.

Output

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.

Events Report

Display a list of the zero duration events from the supplied date range, along with the time of the event. The default date range is today.

The -p option can be supplied 0 or more times to specify the projects shown in the report. If no -p is supplied, all projects are shown.

The optional date range descriptor specifies the dates covered by the report.

Output

  $ rtimelog report events -p dog yesterday today
  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.

Intervals Report

Display a list of the zero duration events from the supplied date range, along with the time between the events. The default date range is today.

The -p option can be supplied 0 or more times to specify the projects shown in the report. If no -p is supplied, all projects are shown.

The optional date range descriptor specifies the dates covered by the report.

Output

The report for an example day might be:

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
  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 events. This actually gives some useful information.

Other Commands

The remaining commands do not necessarily fit into one of the other categories.

Initialize

  $ rtimelog init

Prepare the system for use with rtimelog. First, it creates the directory where rtimelog stores its information, if that directory does not already exist. Then, the command creates and initializes the .timelogrc configuration file, in the user’s home directory, with the information needed to run.

If a directory is not supplied, use the default location of timelog in the user’s home directory.

Edit the Timelog

  $ rtimelog edit

Open the timelog file in the current editor. The editor can be specified in the configuration file. If no editor is specified in the configuration, the program uses the value of the VISUAL environment variable. If VISUAL has no value, then the value of EDITOR is used instead. If neither environment variable has a value, then the program defaults to vim

Archive Previous Year’s Data

  $ rtimelog archive

Move all entries from the earliest year in the logfile, into a new file in the timelog directory named timelog-{year}.txt. No entries are moved from the current year.

Check the Timelog File for Problems

  $ rtimelog check

Walk the logfile and report any problems found with the file.

Get Help on Commands

  $ rtimelog help

Display help about commands. The help command gives more detailed help about the command.

With no arguments, you get a list of the commands, each with its associated help text. The commands are each listed as a usage line with some explanatory text.

Any other argument is looked up in the command list.

List Aliases

  $ rtimelog aliases

List all of the aliases and their expansions from the config file.

Configuration

The rtimelog program uses the file ~/.timelogrc if it exists.

The configuration file is expected to contain data in two major parts:

General Configuration

The first section defined general configuration information in a key=value format. The recognized keys are:

• editor

  The editor to use when opening the timelog file with the edit command. If not specified, it will use the value of either the VISUAL or EDITOR environment variables. If none are found, it will default to vim.

• browser

  The browser command to use when displaying the report generated by the chart command. If not specified, it will use a hard-coded value of chromium, except on Mac OS, where it will use open.

• dir

  The directory in which to find the timelog data files. Defaults to the timelog directory in the user’s home directory.

• defcmd

  The default command to be used if none is supplied to timelog. By default, this is the curr command.

editor=/usr/bin/vim
dir=~/timelog
defcmd=curr
browser=firefox

Command Aliases

The configuration file may also contain an ‘[alias]’ section that defines command aliases. Each alias is defined as a shortname=expansion string.

For example, if you regularly need to make entries for reading email and triaging bug reports you might want the following in your configuration.

[alias]
  email = start +Misc @Email
  triage = start +BugTracker @Triage

Alias Templates

After using rtimelog for a period of time, you will likely find groups of aliases that repeat, with a small number of variations.

I found that I often needed a small set of aliases that were the same except for variations on the project name. The obvious solution for that problem is aliases that work as templates with replaceable parameters.

[alias]
  code  = start +client:{} @Code
  doc   = start +client:{} @Doc
  test  = start +client:{} @Test

The string {} in the expansion string for an alias marks each of these aliases as a template alias. When one of these is used, the first argument after the alias name replaces the first {} string when the alias is expanded. If there is more than one {} in the template alias, each one will take another argument from the command line to replace each {}. If there are more {} than arguments, any {} without a corresponding argument will be left untouched.

Any arguments left after all {} have been replaced will remain on the end of the command.

Assuming the aliases above, if we used the code alias as follows:

  $ rtimelog code Bob New UI

The resulting expanded alias would be the following:

  $ rtimelog start +client:Bob @Code New UI

On the other hand, you could use the doc alias without following arguments, like this

  $ rtimelog test

The expanded alias would be

  $ rtimelog start +client:{} @Test

Appendices

The following sections contain reference material not necessary for most use of rtimelog. If you are curious about the details of the timelog format or history of the project, keep reading.

• Format
• History

Timelog Format, version 2

The format of this file was strongly influenced by the design of the todo.txt system created by Gina Trapani. The major idea was to have a format that could be easily read and modified by a human with a text editor. This format should be a simple as possible, and require no proprietary technology to read or write.

Some of the data stored in the file and the reporting of the data was influenced by years of use of the TEAK tool on the Palm. I wrote this tool to replace TEAK once it was obvious that the Palm was no more.

Description

Each time entry resides on a line by itself. Each line is made up of an optional marker and two parts separated by a marker character, usually a space: a time/date stamp and a task description. There should be no leading or trailing white space on the lines.

The format also supports comments defined as having a # as the first character on the line.

Time/Date Stamp

The time/date stamp is the first thing on each line and is set in the local timezone. Except where we cross from Daylight Saving Time to Standard Time or vice versa this should cause no problems.

The format of this part of the line is ‘YYYY-MM-DD HH:MM:SS’. This format is relatively easy for a person to read, is easily and unambiguously parsed, and sorts nicely.

Entry

The entry is just text that describes the task or event we are now beginning. To enhance reporting, there are two forms of metadata. The first string starting with a + is treated as a project. All events with the same project are reported together. The first string starting with @ is treated as the name of the task. Any remaining text is treated as further detail on the task.

If no task name is specified, all of the event string except the project is treated as the task name. The task name is optional because not everyone will find it useful to define consistent tasks for reporting.

There is one special case. An entry of stop stops timing the current task without starting a new task.

• Examples
• Special Entries

Examples

The following examples should make the format clear.

Full Featured Entry Line

A full entry using all of the features would look line this:

    2013-07-01 10:01:23 +Timelog @Document File Format

The project in this case is Timelog, which specifies that I am working on this module. The task name is Docment, which means I am documenting something on the project. The string ‘File Format’ specifies more detail on what I am documenting.

This task began just after 10:01 on July 1st.

Entry With No Detail

This following entry contains both a project and a task, but with no extra detail.

    2013-07-01 08:05:14 +Admin @Email

In this case, I’m just checking my email for the morning. There is really no need for any more detail than that. Although not a real project, grouping miscellaneous tasks through the day into a Admin pseudo-project simplifies tracking administrative tasks.

Entry with No Explicit Task

    2013-07-01 13:05:45 +Timelog Submit to crates.io

In this case, the task would be ‘Submit to crates.io’ because I haven’t separated the task name from the details.

Entry with No Explicit Task or Project

   2013-07-01 13:14:38 Cleaning desk

This entry has no project for grouping and the task would be ‘Cleaning desk’ because there is not separate task name.

Special Entries

Special entries are points in time that do not feed in to the normal time processing. All special entries have a special character replacing the space after the date stamp that indicates which type of marked entry it is. These entries are not required to perform useful tracking of your time, but they have been found to be useful in later uses of the rtimelog tool.

All special entries are ignored when reporting on times.

Ignored Entries

If the mark character after the time stamp is !, the entry is marked as ignored. This means that a task would have started, but was later ignored.

    2013-07-01 10:01:23!+Timelog @Meeting File Format

A good example would be when a task or meeting is supposed to start, but after just after you mark the time, it gets canceled. Since you won’t spend any time in that task, you don’t want to track it. However the ignored entry marks that it happened, even if it was not actually used in time tracking.

Zero Duration Events

If the mark character after the time stamp is ^, the entry is a zero duration event (or event for short). An event marks something happening at a point in time, rather than an entry for at one end of a span of time.

    2013-07-01 10:01:23^+Timelog System restart

For example, you might use a event to indicate when an alert happens, or to mark when during the day that some irregular event occurs.

History of timelog/rtimelog

In a job a long time ago, I found that I would regularly reach the end of a long, tiring day and have no idea what I had done. Just as regularly, I found that my most important projects were not progressing very rapidly. Many people find themselves in the same position. I decided to do something about it, I found an application on the Palm that tracked Clients, Projects, and Tasks (as well as mileage and expenses) called TEAK.

I started tracking everything I did at work. After a few days, I had identified many of the interruptions that prevented me from making progress. I had also noted that some of my busiest, yet least productive days were almost all interruptions. I used this information to improve my work and to keep people updated with why my various projects were not progressing as expected. When I needed to make faster progress, I had the data to help my manager redirect the worst of the interruptions.

The Need for Change

This was wonderful. Unfortunately, the Palm platform did not survive in the market. I continued to keep my Palm functional partially to use TEAK. But, I eventually had to admit that I could not rely on my Palm to continue. By this time I had an Android smart phone and I figured it would be pretty easy to find something to replace TEAK. No such luck.

I had been using Gina Trapani’s Todo.txt program for a while at this point. It’s main feature is the simplicity of its file format:

• One entry per line
• pure text
• minimal formatting

I decided that this would be a better basis for a new time logging program than some binary format. So I wrote a quickie Perl script to allow me to start and stop task timers and to generate simple reports.

As I used the program, I found other commands and reports that could be useful. In the end, it was obvious that this tool needed to be cleaned up a re-written. The Perl module version was the result of that rewrite. I used that version of the program for nearly a decade.

While learning Rust, I decided to make a project out of porting of the Perl program to Rust. Mostly it was an excuse to move beyond the toy exercises that dominate the beginning of learning any new language. Partly though, it was an attempt to explore the features of Rust in a closer to real world application without the risk of depending on my new understanding for something in production.

The current version of the Rust project has diverged from the Perl version, and implements version 2 of the time log format.