tiempo-rs/docs/source/index.rst

Tiempo
======

Synopsys
--------

**t** [-h|--help]

**t** [-V|--version]

**t** archive

**t** backend

**t** configure

**t** display

**t** edit

**t** help

**t** in

**t** kill

**t** list

**t** month

**t** now

**t** out

**t** resume

**t** sheet

**t** today

**t** week

**t** yesterday

Description
-----------

Tiempo is a command-line time tracker. Register the start and end times of your
activities and get results by day, week, month or custom periods of time in
different formats, including custom ones.

You can also group your entries by 'sheet' to organize different
projects/clients/etc.

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
                              chart, text (default), ical, csv, json and ids.
                              Check the docs on defining custom formats bellow.
    -g, --grep <regexp>       Include entries where the note matches this regexp

Some shortcuts available are:

`today` - Display entries that started today

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

`yesterday` - Display entries that started yesterday

    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 or a specified one.

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

Per command default formatters
..............................

**New in 1.4.0**

It might be the case that you want to use one default formatter for when you use
`t week` and a different one for `t month` or `t today`. That's what per-command
default formatters are for. To use them just add a `commands` section to your
config file and set `default_formatter` on some formatters. This is what it
would look like:

**In toml**

.. code:: toml

   [commands.week]
   default_formatter = "chart"

   [commands.month]
   default_formatter = "ical"

**In yaml**

.. code:: yaml

   commands:
     week:
       default_formatter: chart
     month:
       default_formatter: ical

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 [OPTIONS] [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.
    -t, --time <hours>        Only archive up to `hours` hours.

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

Configuration
.............

`tiempo` keeps a config file, whose location you can learn usign `t configure`.
It is also possible to edit the config file in-place passing arguments to
`t configure` like this:

    t c --append-notes-delimiter ';'

it will print the resulting config file. Beware that it wont keep comments added
to the file.

Commands
--------

where individual commands are described

t-in
....

login

Files and paths
---------------

explain the config file, and database path

Specifying times
----------------

Some arguments accept a time as value, like `t in`'s `--at` or `t d --start`.
These 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`

Default formatters
------------------

Tiempo comes with a handful of formatters that display your entries in different
ways. Here's the full list.

chart
.....

(New in 1.4.0) Displays a nice chart of the weekly progress.

**Settings**

By default this formatter will only display a nice chart of the progress divided
by week and respecting the `week_start` setting. However you may specify a daily
goal and a weekly goal to customize the chart, as well as how many minutes each
character represents:

In toml:

.. code:: toml

   [formatters.chart]
   daily_goal_hours = 4
   weekly_goal_hours = 20
   character_equals_minutes = 30

In yaml:

.. code:: yaml

   formatters:
     chart:
       daily_goal_hours: 4
       weekly_goal_hours: 20
       character_equals_minutes: 30

text
....

Displays nicely the entries grouped by sheet and day.

ical
....

This formatter's output can be redirected to a file and then uploaded to a
calendar app.

csv
...

Basically dump the entries as CSV to stdout. Useful for passing entries to a
different tool.

json
....

Dump the entries in JSON format.

ids
...

Dump only the ids in a single line

Custom formatters
-----------------

You can implement your own formatters for all subcommands that display entries
(like `t display`, `t week` etc.). It is as easy as creating an executable file
written in any programming language (interpreted or compiled) and placing it in
a path listed in the config value for `formatter_search_paths`.

This executable will be given as standard input a csv stream with each row
representing a time entry with the same structure as the `csv` formatter output.
It will also be given a command line argument representing user settings for
this formatter stored in the config file and formatted as JSON.

Example
.......

Suppose we have this config file:

.. code:: toml

   database_file = "/home/user/.config/tiempo/database.sqlite3"
   round_in_seconds = 900
   append_notes_delimiter = " "
   formatter_search_paths = ["/home/user/.config/tiempo/formatters"]
   default_formatter = "text"
   auto_sheet = "dotfiles"
   auto_sheet_search_paths = ["/home/user/.config/tiempo/auto_sheets"]
   auto_checkout = false
   require_note = true
   week_start = "Monday"

   [formatters.earnings]
   hourly_rate = 300
   currency = "USD"

then we can create the `earnings` formatter by placing the following file in
`/home/user/.config/tiempo/formatters/earnings`:

.. code:: python

   #!/usr/bin/env python3
   import sys
   import json
   import csv
   from datetime import datetime, timezone
   from datetime import timedelta
   from math import ceil

   config = json.loads(sys.argv[1])

   reader = csv.DictReader(
       sys.stdin,
       fieldnames=['id', 'start', 'end', 'note', 'sheet'],
   )

   total = timedelta(seconds=0)

   for line in reader:
       start = datetime.strptime(line['start'], '%Y-%m-%dT%H:%M:%S.%fZ')

       if not line['end']:
           end = datetime.utcnow()
       else:
           end = datetime.strptime(line['end'], '%Y-%m-%dT%H:%M:%S.%fZ')

       total += end - start

   hours = total.total_seconds() / 3600
   earnings = hours * config['hourly_rate']
   currency = config['currency']

   print(f'You have earned: ${earnings:.2f} {currency}')

Now if you run `t display -f earnings` you will get something like:

.. code:: text

   You have earned: 2400 USD