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