This manual applies to rtimelog
version 1.0.
INTRODUCTION
For reasons explained in the History document, 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 document.
The rtimelog
Program
The rtimelog
program manipulates your time log and generates reports. The program
is executed with a command and optional arguments.
Supported Commands
The rtimelog
program supports a number of commands that manipulate or report
on the time logged by the program.
Starting Tasks
The commands you will use the most involve adding events to the time log. The
string {task description}
is a text string that may have a +project and/or
a @taskname. The first string of non-whitespace characters beginning with a '+
'
is treated as the project for this event. The project is only relevant when
using the reporting commands. Likewise, the first string of non-whitespace
characters beginning with a '@
' is treated as a task name.
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.
start
{task description}Stop the current task and start timing a new task. Since
rtimelog
only tracks one task at a time, the current task is always stopped when starting a new task.stop
Stop timing the current task.
push
{task description}Save the current task description on stack and start timing new task. The current task description is saved in the stack file in the timelog directory. You can manipulate the saved task description with resume, or one of the stack commands.
resume
Stop the current task and restart top task from the stack. This also removes the task description from the stack.
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.
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.
comment
{comment text}Add a comment line to the logfile.
event
{event text}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 task.
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 subcommands cover many
of those small edits. The supported subcommands are:
entry discard
Discard the most recent entry from the logfile. This is useful if you started a new task without meaning to.
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 changed. The ignored entry does not contribute to reports in any way.
A good use for the 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.
I found that most of the time I used the edit
command was to adjust the time of the most
recent entry. Quite often I would start typing the command a bit before starting a meeting
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.
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.
entry rewrite
{task description}Replace the task description on the most recent entry.
entry was
{hh:mm|hh:mm:ss}Reset the time on the most recent entry
entry rewind
{minutes}Shift the time on the most recent entry back the specified number of minutes.
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 subcommands to perform different actions on the stack
file. Those subcommands are:
stack ls
Display items on the stack. The top task description on the stack is the one that is resumed by the resume command.
stack top
Display just the top item on the stack.
stack clear
Clear the stack file.
stack drop
[{n}]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.
stack keep
[{n}]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 then
topmost are discarded.
Informational Commands
There are a number of commands that display some information from the timelog file.
ls
[date]List entries for the specified day. See the Reporting section that follows for information about date formats. Default to today.
lsproj
List known projects, one per line.
curr
Display the start date and time and task description of the current task, if any.
Reporting
The reporting commands generate a report of information from the timelog file. Many of these commands accept a date range descriptor. A date range descriptor can take one of the following forms:
Single Date
A single date 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.
This will result in a range spanning one day.
Date Pair
A pair of dates in 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.
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 the range description is this followed by week, month, or year, the resultant range covers:
- week: from the last Sunday to Saturday of this week,
- month: from the first day of the current month to last day of the month,
- 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:
- week: from the two Sundays ago to last Saturday,
- month: from the first of the month before this one to the last day of that month,
- 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.
Any time you supply a pair of dates, the second must be later in time than the first.
Individual Reports
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:
report hours
[-p proj] [date [end date]]Display the hours worked for each of the appropriate days. The default date range is today.
report detail
[-p proj] [date [end date]]Display a report for the specified days.
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.
report summary
[-p proj] [date [end date]]Display a summary of the appropriate days' projects.
For each day, the list of projects active during that day is shown along with the aggregate time spent on that project. The default date range is today.
report chart
[date [end date]]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 default date range is today.
report events
[-p proj] [date [end date]]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.
report intervals
[-p proj] [date [end date]]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.
Other Commands
The remaining commands do not necessarily fit into one of the other categories.
init
[dir]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
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. IfVISUAL
has no value, then the value ofEDITOR
is used instead. If neither environment variable has a value, then the program defaults tovim
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
Walk the logfile and report any problems found with the file.
help
[command]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.
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 theVISUAL
orEDITOR
environment variables. If none are found, it will default tovim
.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 ofchromium
, except on Mac OS, where it will useopen
.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.
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
If the expansion contains the string {}
, it will be replaced with the first
argument after the alias name from the command line. This will continue until
all {}
strings are replaced. If we try to replace a {}
and there is no
corresponding argument, the {}
will be left in place.