# Overview of `rtimelog`
## VERSION
This manual applies to rtimelog version 0.46.
## INTRODUCTION
For reasons explained in the [History][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][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 an 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 on 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.
- `check`
Walk the logfile and report any problems found with the file.
- `comment`
Add a comment line to the logfile.
- `event`
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.
### Task Manipulation Commands
The `task` 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. This commands cover many
of those small edits. The supported subcommands are:
- `task discard`
Discard the most recent entry from the logfile. This is useful if you started
a new task without meaning to.
- `task 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.
- `task 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.
- `task rewrite`
Replace the task description on the most recent entry.
### Stack Manipulation
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 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 clear`
Clear the stack file.
- `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 the `n` 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_ or pair of _date_ s. The date is
normally expected to be of the form `YYYY-MM-DD`. However, a small number
of shortcuts are also allowed.
The strings '_today_' and '_yesterday_' resolve to the obvious date. The days
of the week are also allowed, each resolves to that day of the week prior to the
current day. If the current day is Wednesday, _monday_ resolves to two days ago,
_thursday_ resolves to six days ago, and _wednesday_ resolves to one week ago.
Any time you supply a pair of dates, the second must be later in time than the
first.
The reporting commands are:
- `report hours` \[date \[end date\]\]
Display the hours worked for each of the appropriate days. The default date
range is *today*.
- `report detail` \[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` \[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` \[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*.
### 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. 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`
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.
- `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 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 by 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.
[history]: History.md
[format]: Format.md
## AUTHOR
G. Wade Johnson `<rust@gwadej.org>`
## LICENCE AND COPYRIGHT
Copyright (c) 2021-2022, G. Wade Johnson `<rust@gwadej.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](https://opensource.org/licenses/Artistic-2.0).