Tiempo

A timetrap compatible command line time tracking application.

Tutorial

First of all, you can abbreviate all commands to their first letter, so t in and t i are equivalent.

Managing entries

Register the start of an activity in the default timesheet with:

t in 'Doing some coding'

which sets the activity's start time to the current time. Later when you're done use

t out

to mark it as finished. If you forgot to start the activity before you can do so with:

t i --at '20 min ago'

the same applies for t out.

Edit an entry with

t edit [options]

where the options are

-i, --id <id:i>           Alter entry with id <id> instead of the running entry
-s, --start <time:qs>     Change the start time to <time>
-e, --end <time:qs>       Change the end time to <time>
-a, --append              Append to the current note instead of replacing it
                          the delimiter between appended notes is
                          configurable (see configure)
-m, --move <sheet>        Move to another sheet

You can remove an entry with

t kill --id 123

or an entire timesheet with

t kill somesheet

check bellow to see how to get the ids.

Displaying entries

At any point in time you can check your time spent in the current or other timesheet with:

t display [options] [SHEET | all | full]

the available options are

-v, --ids                 Print database ids (for use with edit)
-s, --start <date:qs>     Include entries that start on this date or later
-e, --end <date:qs>       Include entries that start on this date or earlier
-f, --format <format>     The output format.  Valid built-in formats are
                          ical, csv, json, ids, factor, and text (default).
                          Check the docs on defining custom formats bellow.
-g, --grep <regexp>       Include entries where the note matches this regexp

Some shortcuts available are:

today - Shortcut for display with start date as the current day

t today [--ids] [--format FMT] [SHEET | all]

yesterday - Shortcut for display with start and end dates as the day before the current day

t yesterday [--ids] [--format FMT] [SHEET | all]

week - Entries of this week so far. The default start of the week is Monday (configurable).

t week [--ids] [--end DATE] [--format FMT] [SHEET | all]

month - Entries of this month of a specified one.

t month [--ids] [--start MONTH] [--format FMT] [SHEET | all]

Using different timesheets

You can organize your activities in different timesheets by first switching to an existing one, then starting an activity:

t sheet somename
t in 'some activity'

which will also create the timesheet if it doesn't exist.

List all existing timesheets using

t list [all]

(defaults to not showing archive timesheets with names preceded by an underscore)

Advanced management

You can archive entries from a timesheet using:

t archive [--start DATE] [--end DATE] [SHEET]

which defaults to archiving all entries in the current sheet, or you can be more specific using these options:

-s, --start <date:qs>     Include entries that start on this date or later
-e, --end <date:qs>       Include entries that start on this date or earlier
-g, --grep <regexp>       Include entries where the note matches this regexp.

This subcommand will move the selected entries to a hidden timesheet named _[SHEET] (the name of the timesheet preceded by an underscore).

It is possible to access directly the sqlite database using

t backend

Specifying times

Some arguments accept a time as value, like t in's --at or t d --start. This are the accepted formats:

Something similar to ISO format will be parsed as a time in the computer's timezone.

• 2021-01-13 a date
• 2019-05-03 11:13 a date with portions of a time

ISO format with offset or UTC will be parsed as a time in the specified timezone. Use Z for UTC and an offset for everything else

• 2021-01-13Z
• 2005-10-14 19:20:35+05:00

something that looks like an hour will be parsed as a time in the current day in the computer's timezone. Add Z or an offset to specify the timezone.

• 11:30
• 23:50:45 (with seconds)

some human times, for now restricted to time ago:

• an hour ago
• a minute ago
• 50 min ago
• 1h30m ago
• two hours thirty minutes ago

How to build

You need rust, then clone the repo and simply run

cargo test

to check that everything is working, and then

cargo build --release

to have a binary at target/release/t that you can then move to a directory in your PATH or use it by its absoulte or relative paths.

Run

t --help

to see the options.