move current docs from readme to docs
This commit is contained in:
parent
a41817f438
commit
efc5055262
340
README.md
340
README.md
|
@ -1,7 +1,7 @@
|
||||||
# Tiempo
|
# Tiempo
|
||||||
|
|
||||||
A [timetrap](https://github.com/samg/timetrap/) compatible command line time
|
A [timetrap](https://github.com/samg/timetrap/) compatible command line time
|
||||||
tracking application.
|
tracking application. [Read the fine manual](https://tiempo.categulario.xyz).
|
||||||
|
|
||||||
## Installation
|
## Installation
|
||||||
|
|
||||||
|
@ -36,333 +36,6 @@ inside the repository. The binary will be named `t` (or `t.exe` if you use
|
||||||
windows) and it is located inside the `target/release` directory that was
|
windows) and it is located inside the `target/release` directory that was
|
||||||
created during compilation.
|
created during compilation.
|
||||||
|
|
||||||
## 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**
|
|
||||||
|
|
||||||
```toml
|
|
||||||
[commands.week]
|
|
||||||
default_formatter = "chart"
|
|
||||||
|
|
||||||
[commands.month]
|
|
||||||
default_formatter = "ical"
|
|
||||||
```
|
|
||||||
|
|
||||||
**In yaml**
|
|
||||||
|
|
||||||
```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.
|
|
||||||
|
|
||||||
## 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:
|
|
||||||
|
|
||||||
```toml
|
|
||||||
[formatters.chart]
|
|
||||||
daily_goal_hours = 4
|
|
||||||
weekly_goal_hours = 20
|
|
||||||
character_equals_minutes = 30
|
|
||||||
```
|
|
||||||
|
|
||||||
In yaml:
|
|
||||||
|
|
||||||
```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:
|
|
||||||
|
|
||||||
```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`:
|
|
||||||
|
|
||||||
```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:
|
|
||||||
|
|
||||||
```
|
|
||||||
You have earned: 2400 USD
|
|
||||||
```
|
|
||||||
|
|
||||||
## Why did you write this instead of improving timetrap?
|
## Why did you write this instead of improving timetrap?
|
||||||
|
|
||||||
* timetrap is [hard to install](https://github.com/samg/timetrap/issues/176),
|
* timetrap is [hard to install](https://github.com/samg/timetrap/issues/176),
|
||||||
|
@ -431,20 +104,19 @@ first you need to install it somehow. Two options I can offer are:
|
||||||
you have python 3.9 on your computer, enter the `docs` directory and do
|
you have python 3.9 on your computer, enter the `docs` directory and do
|
||||||
`pipenv install`.
|
`pipenv install`.
|
||||||
|
|
||||||
To build the docs just enter the `docs` directory and some of the language
|
To build the docs just enter the `docs` directory and run:
|
||||||
directories (currently `es` or `en`) and run:
|
|
||||||
|
|
||||||
make html
|
make html
|
||||||
|
|
||||||
for the html version (output located at `docs/<lang>/build/html`), or
|
for the html version (output located at `docs/build/html`), or
|
||||||
|
|
||||||
make man
|
make man
|
||||||
|
|
||||||
for the man page (output located at `docs/<lang>/build/man/tiempo.1`). If you
|
for the man page (output located at `docs/build/man/tiempo.1`). If you
|
||||||
are using pipenv just prefix the commands with `pipenv run` or run `pipenv
|
are using pipenv just prefix the commands with `pipenv run` or run `pipenv
|
||||||
shell` before running any command.
|
shell` before running any command.
|
||||||
|
|
||||||
The contents of the docs are located in `docs/<lang>/source/index.rst`,
|
The contents of the docs are located in `docs/source/index.rst`,
|
||||||
formatted as
|
formatted as
|
||||||
[reStructuredText](https://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html).
|
[reStructuredText](https://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html).
|
||||||
|
|
||||||
|
@ -459,7 +131,7 @@ for and whose design I took as reference, keeping compatibility when possible.
|
||||||
(mostly to remind myself)
|
(mostly to remind myself)
|
||||||
|
|
||||||
* [ ] Ensure tests pass and that clippy doesn't complain
|
* [ ] Ensure tests pass and that clippy doesn't complain
|
||||||
* [ ] Add documentation to the readme on the new features
|
* [ ] Add documentation about the new features
|
||||||
* [ ] Create an entry in `CHANGELOG.md` with the target version, stage it but
|
* [ ] Create an entry in `CHANGELOG.md` with the target version, stage it but
|
||||||
don't commit
|
don't commit
|
||||||
* [ ] run `vbump`
|
* [ ] run `vbump`
|
||||||
|
|
|
@ -1,20 +1,412 @@
|
||||||
.. Tiempo documentation master file, created by
|
Tiempo
|
||||||
sphinx-quickstart on Sat Sep 17 22:33:18 2022.
|
======
|
||||||
You can adapt this file completely to your liking, but it should at least
|
|
||||||
contain the root `toctree` directive.
|
|
||||||
|
|
||||||
Welcome to Tiempo's documentation!
|
Synopsys
|
||||||
==================================
|
--------
|
||||||
|
|
||||||
.. toctree::
|
**t** [-h|--help]
|
||||||
:maxdepth: 2
|
|
||||||
:caption: Contents:
|
|
||||||
|
|
||||||
|
**t** [-V|--version]
|
||||||
|
|
||||||
|
**t** archive
|
||||||
|
|
||||||
Indices and tables
|
**t** backend
|
||||||
==================
|
|
||||||
|
|
||||||
* :ref:`genindex`
|
**t** configure
|
||||||
* :ref:`modindex`
|
|
||||||
* :ref:`search`
|
**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
|
||||||
|
|
Loading…
Reference in New Issue