tiempo-rs/docs/source/index.rst

Tiempo
======

Synopsys
--------

**t** -h|--help

**t** help SUBCOMMAND

**t** SUBCOMMAND -h|--help

**t** SUBCOMMAND [OPTIONS]

Subcommands
-----------

+-----------+-------+----------------------------------------------------------+
| Command   | Alias | Description                                              |
+===========+=======+==========================================================+
| archive   | a     | Archive entries to a hidden timesheet.                   |
+-----------+-------+----------------------------------------------------------+
| backend   | b     | Open an sqlite shell to the database (requires having    |
|           |       | sqlite3 installed.                                       |
+-----------+-------+----------------------------------------------------------+
| configure | c     | Configure tiempo in-place or get path to config file.    |
+-----------+-------+----------------------------------------------------------+
| display   | d     | Display all entries in the current sheet.                |
+-----------+-------+----------------------------------------------------------+
| edit      | e     | Edit an entry.                                           |
+-----------+-------+----------------------------------------------------------+
| in        | i     | Start an entry in the current timesheet.                 |
+-----------+-------+----------------------------------------------------------+
| kill      | k     | Delete an entry or an entire timesheet.                  |
+-----------+-------+----------------------------------------------------------+
| list      | l     | List existing sheets.                                    |
+-----------+-------+----------------------------------------------------------+
| month     | m     | Display entries starting this month.                     |
+-----------+-------+----------------------------------------------------------+
| now       | n     | Show all running entries.                                |
+-----------+-------+----------------------------------------------------------+
| out       | o     | End the active entry in the current timesheet.           |
+-----------+-------+----------------------------------------------------------+
| resume    | r     | Restart the timer for an entry. Defaults to the last     |
|           |       | active entry.                                            |
+-----------+-------+----------------------------------------------------------+
| sheet     | s     | Switch to a new or existing timesheet.                   |
+-----------+-------+----------------------------------------------------------+
| today     | t     | Display entries that started today.                      |
+-----------+-------+----------------------------------------------------------+
| week      | w     | Display entries starting last monday or later (First day |
|           |       | of the week configurable).                               |
+-----------+-------+----------------------------------------------------------+
| yesterday | y     | Display entries that started 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.

Entries are optionally organized in timesheets which you can use to represent
projects, clients etc. Most commands (notably the ones that display entries)
work on the *current* or *active* timesheet.

The entries are stored in a local Sqlite3 database whose location you can learn
by looking at your config file (whose location you can learn running ``t c``).

**tiempo** stores entries as UTC and then converts to the local timezone for
displaying and querying. This means that even if you change timezones your
recorded times will be correct, although their displayed results might vary if
grouping by day for example.

This tool is compatible with a previous one with the same purpose called
``timetrap``. The most notable difference being that timetrap stores times as
local timezone times, which makes it messy if you switch timezones. Another
difference is that in timetrap you used the internal ruby API to add custom
display formats and in ``tiempo`` you'll use standard input/output and
command-line arguments in any language of your choice.

Tutorial
--------

.. note::

   yo, doc this

Commands
--------

.. note::

   TODO finish this

t-in
....

login

Settings
--------

.. note::

   describe the settings file

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

.. note::

   likely move this to the section above

**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

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

.. note::

   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:

.. code:: text

     Date  Day Chart      Hours

   Sep  5  Mon #######    3.8
        6  Tue ####       2.3
        7  Wed #######    3.9
        8  Thu            0.0
        9  Fri #########  4.5
       10  Sat #########  4.7
       11  Sun            0.0

          Week 19.3/20.0

**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. This is the default
formatter. Pass ``-v`` to also reveal each entry's id:

.. code:: text

   Timesheet: foo
       Day                Start      End        Duration Notes
       Tue Sep 20, 2022   09:09:58 - 09:40:13    0:30:15 write tiempo's docs
                          09:41:01 - 10:11:20    0:30:18 work on pizarra.categulario.xyz
                                                 1:00:34
   -------------------------------------------------------------------------------------
       Total                                     1:00:34

ical
....

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

.. code:: text

   BEGIN:VCALENDAR
   CALSCALE:GREGORIAN
   METHOD:PUBLISH
   PRODID:tiempo-rs
   VERSION:2.0
   BEGIN:VEVENT
   DESCRIPTION:write tiempo's docs
   DTEND:20220920T134013Z
   DTSTAMP:20220920T130958Z
   DTSTART:20220920T130958Z
   SEQUENCE:0
   SUMMARY:write tiempo's docs
   UID:tiempo-10@abraham-lenovo-t470s
   END:VEVENT
   BEGIN:VEVENT
   DESCRIPTION:work on pizarra.categulario.xyz
   DTEND:20220920T141120Z
   DTSTAMP:20220920T134101Z
   DTSTART:20220920T134101Z
   SEQUENCE:0
   SUMMARY:work on pizarra.categulario.xyz
   UID:tiempo-11@abraham-lenovo-t470s
   END:VEVENT
   END:VCALENDAR

csv
...

Dump the entries as CSV to stdout. Useful for passing entries to a different
tool. Pass ``-v`` to add an ``id`` column.

.. code:: text

   start,end,note,sheet
   2022-09-20T13:09:58.805280Z,2022-09-20T13:40:13.837994Z,write tiempo's docs,foo
   2022-09-20T13:41:01.478854Z,2022-09-20T14:11:20.461322Z,work on pizarra.categulario.xyz,foo

json
....

Dump the entries in JSON format:

.. code:: json

   [{"id":10,"note":"write tiempo's docs","start":"2022-09-20T13:09:58.805280283Z","end":"2022-09-20T13:40:13.837994932Z","sheet":"foo"},{"id":11,"note":"work on pizarra.categulario.xyz","start":"2022-09-20T13:41:01.478854071Z","end":"2022-09-20T14:11:20.461322041Z","sheet":"foo"}]

ids
...

Dump only the ids in a single line:

.. code:: text

   2196 2197 2198 2199 2200 2201

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`` and making it executable:

.. code:: python

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

   # Settings for this formatter passed as the first argument
   config = json.loads(sys.argv[1])

   reader = csv.DictReader(
       sys.stdin,  # entries are received from stdin
       fieldnames=['id', 'start', 'end', 'note', 'sheet'],
   )

   total = timedelta(seconds=0)

   for line in reader:
       # times are formatted as ISO format
       start = datetime.strptime(line['start'], '%Y-%m-%dT%H:%M:%S.%fZ')

       # entries that are still running don't have a value in the 'end' column
       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
   # use the settings
   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