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

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

t-archive
.........

``t a|archive [OPTIONS] [SHEET]``

By default this command will ask for you confirmation, then archive ALL entries
in the current timesheet. Pass ``--fake`` to only display the entries using the
``text`` formatter (useful if you want to make sure that the archived
time/entries are correct).

Using ``--start`` and ``--end`` you can further limit the period of time that
will be archived (See **Specifying times** section of the docs on the accepted
formats). You can use ``--grep`` to only archive certain entries that match the
given regular expression.

If what you need is to archive a specific elapsed time, for example only 15
hours out of however many the timesheet has use ``--time`` with the amount of
hours you want to archive.

**Options**

-f, --fake
   Don't actually archive the entries, just display them

-e, --end <TIME>
   Include entries that start on this date or earlier

-g, --grep <REGEXP>
   Include entries where the note matches this regexp.

-s, --start <TIME>
   Include entries that start on this date or later

-t, --time <HOURS>
   Time in hours to archive. Archived time will be equal or less than this.

``SHEET``
   Archive entries from this timesheet instead of the current one.

t-backend
.........

``t b|backend``

Open a sqlite3 shell into the database. Sqlite3 must be installed  and in the
``PATH`` variable for this command to work.

t-configure
...........

``t c|configure [OPTIONS]``

If called without arguments ``t c`` will print the absoulte path to the config
file. If you pass arguments they'll be used to edit your config file in place.

.. warning::

   This will erase any comments you might have added to your toml or yaml file.
   It is better to edit the config file manually with your preferred text
   editor:

   .. code:: shell-session

      vim $(t c)

**Options**

--auto-checkout
   Checkout of current running entry when starting a new one. **Not
   implemented**.

--no-auto-checkout
   Starting a new entry fails if one is running (default).

--no-require-note
   Entries can be created without a note.

--require-note
   Prompt for a note if one isn't provided when checking in (default).

--append-notes-delimiter <DELIMITER>
   delimiter used when appending notes via t edit --append. Default: ' '
   (space).

--database-file <PATH>
   Set the absoulte path to the sqlite database. A new database will be created
   at this location if one does not exist.

--default-formatter <FORMATTER>
   The format to use when display commands are invoked without a ``--format``
   option. Defaults to ``'text'``. See **Settings** section of the docs for
   per-command default formatter.

``--formatter-search-paths <PATH>[,<PATH>...]``
   comma separated paths to search for user defined fomatters. See **Custom
   formatters** section for more info on this.

--interactive-entries <N>
   How many unique previous notes to show when selecting interactively. An
   example of an interactive command is ``t resume -i``.

--note-editor <EDITOR>
   Specify a custom command used to edit an entry's note. Default: $EDITOR

--round-in-seconds <SECONDS>
   The duration of time to use for rounding with the -r flag. Default: 900 (15
   m). **Not implemented**.

--week-start <DAY>
   The day of the week to use as the start of the week for t week. Default:
   monday [possible values: monday, tuesday, wednesday, thursday, friday,
   saturday, sunday]

.. _t-display:

t-display
.........

``t d|display [OPTIONS] [SHEET|all|full]``

Display all entries in the current timesheet using the specified formatter (by
default this is ``text``). For more information on formatters see
:ref:`default-formatters`. For information on custom formatters see
:ref:`custom-formatters`.

It is worh noting that **BOTH** the ``--start`` and ``--end`` arguments act on
the start time of the entry.

**Options**

-v, --ids
   Print database ids (for use with edit).

-e, --end <TIME>
   Include entries that start on this date or earlier.

-f, --format <FORMAT>
   The output format. Valid built-in formats are chart, text, ical, csv, json
   and ids. See :ref:`default-formatters` for more info. See
   :ref:`custom-formatters` to learn how to make your own.

-g, --grep <REGEXP>
   Only display entries whose notes match this regular expression.

-s, --start <TIME>
   Include entries that start on this date or later.

``<SHEET>``
   The sheet to display. Pass 'all' to see entries from all sheets or 'full' to
   see hidden entries.

edit
....

help
....

in
..

kill
....

list
....

t-month
.......

``t m|month [OPTIONS] [SHEET|all|full]``

Like :ref:`t-display` but only display entries that started this month in the
current timezone. Pass ``--month MONTH`` to display entries of different months.

Just like ``t-display`` this accepts ``--grep``, ``--ids``, and ``--format``.

now
...

out
...

resume
......

sheet
.....

t-today
.......

``t t|today [OPTIONS] [SHEET|all|full]``

Like :ref:`t-display` but only display entries that started today in the current
timezone. Pass ``--end`` to further filter entries that started earlier than the
given time.

Just like ``t-display`` this accepts ``--grep``, ``--ids``, and ``--format``.

t-week
......

``t w|week [OPTIONS] [SHEET|all|full]``

Like :ref:`t-display` but only display entries that started this week in the
computer's timezone. The first day of the week by default is ``monday`` but this
is configurable. See :ref:`settings` and :ref:`t-configure`.

Just like ``t-display`` this accepts ``--grep``, ``--ids``, and ``--format``.

t-yesterday
...........

``t y|yesterday [OPTIONS] [SHEET|all|full]``

Like :ref:`t-display` but only display entries that started yesterday in the
computer's current timezone.

Just like ``t-display`` this accepts ``--grep``, ``--ids``, and ``--format``.

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:

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:

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