375 lines
11 KiB
ReStructuredText
375 lines
11 KiB
ReStructuredText
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 sheet so they are out of the |
|
|
| | | way |
|
|
+-----------+-------+----------------------------------------------------------+
|
|
| backend | b | Open an sqlite shell to the database. |
|
|
+-----------+-------+----------------------------------------------------------+
|
|
| 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 activity in the current timesheet |
|
|
+-----------+-------+----------------------------------------------------------+
|
|
| kill | k | Delete an entry or an entire sheet |
|
|
+-----------+-------+----------------------------------------------------------+
|
|
| 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 | Change active timesheet or list existing timesheets |
|
|
+-----------+-------+----------------------------------------------------------+
|
|
| today | t | Display entries that started today |
|
|
+-----------+-------+----------------------------------------------------------+
|
|
| week | w | Display entries starting last monday or later |
|
|
+-----------+-------+----------------------------------------------------------+
|
|
| 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.
|
|
|
|
You can also group your entries by 'sheet' to organize different
|
|
projects/clients/etc.
|
|
|
|
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
|