tiempo-rs/README.md

# Tiempo

A [timetrap](https://github.com/samg/timetrap/) compatible command line time
tracking application. [Read the fine manual](https://tiempo.categulario.xyz).

## Installation

### For Archlinux (and derivatives) users

There are a binary and a source package in the AUR:

* [tiempo-bin](https://aur.archlinux.org/packages/tiempo-bin)
* [tiempo-git](https://aur.archlinux.org/packages/tiempo-git)

### For every other linux users

Go to [gitlab releases page](https://gitlab.com/categulario/tiempo-rs/-/releases)
and grab the latest binary for your linux. There is a `.deb` file for Debian and
Ubuntu as well as a binary for any `x86_64` Linux.

### For Rust developers

You have `cargo`! you can run:

    cargo install tiempo

### For everyone else

You need to compile `tiempo` by yourself. But don't worry! It is not that hard.
Just clone [the repository](https://gitlab.com/categulario/tiempo-rs), make sure
you have [rust installed](https://rustup.rs) and run:

    cargo build --release

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
created during compilation.

## Why did you write this instead of improving timetrap?

* timetrap is [hard to install](https://github.com/samg/timetrap/issues/176),
  hard to keep [updated](https://github.com/samg/timetrap/issues/174) (because
  of ruby). With tiempo you can get (or build) a binary, put it somewhere in
  your `PATH`, and it will just work forever in that machine. I'm bundling
  sqlite.
* timetrap is slow (no way around it, because of ruby), some commands take up to
  a second. Tiempo always feels snappy.
* needed major refactor to fix the timezone problem (in a language I'm not
  proficient with). I was aware of this problem and designed tiempo to store
  timestamps in UTC while at the same time being able to work with a database
  made by timetrap without messing up. And there are a lot of tests backing this
  assertions.

### Other advantages

* Columns in the output are always aligned.
* Fixed some input inconsistencies.
* CLI interface is easier to discover (ask -h for any sub-command)
* End times are printed with +1d to indicate that the activity ended the next
  day in the 'text' formatter.
* Solved some old issues in timetrap.
* Added new features!

## How to build

You need [rust](https://rustup.rs), then clone the repo and simply run

    cargo test

to check that everything is working, and then

    cargo build --release

to have a binary at `target/release/t` that you can then move to a
directory in your `PATH` or use it by its absoulte or relative paths.

Run

    t --help

to see the options.

### Development database

When developing I prefer not to mess with my own database, so I use this `.env`
file:

    export TIMETRAP_CONFIG_FILE=/absolute/path/to/repo/dev_config.toml
    PS1="$ "

and when I want to test some commands against such config file I just source it:

    source .env
    cargo run -- in 'hola'

### Documentation

The docs are written using [sphinx](https://www.sphinx-doc.org/en/master/), so
first you need to install it somehow. Two options I can offer are:

* using your computer's package manager. Install a package with a name similar
  to `python-sphinx`.
* using [pipenv](https://duckduckgo.com/?t=ffab&q=pipenv&ia=web). Just ensure
  you have python 3.9 on your computer, enter the `docs` directory and do
  `pipenv install`.

To build the docs just enter the `docs` directory and run:

    make html

for the html version (output located at `docs/build/html`), or

    make man

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
shell` before running any command.

The contents of the docs are located in `docs/source/index.rst`,
formatted as
[reStructuredText](https://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html).

## Special Thanks

To [timetrap](https://github.com/samg/timetrap) for existing, to
[samg](https://github.com/samg) for creating it. It is the tool I was looking
for and whose design I took as reference, keeping compatibility when possible.

## Release checklist

(mostly to remind myself)

* [ ] Ensure tests pass and that clippy doesn't complain
* [ ] Add documentation about the new features
* [ ] Create an entry in `CHANGELOG.md` with the target version, stage it but
  don't commit
* [ ] run `vbump`
* [ ] git push && git push --tags && cargo publish && cargo build --release && cp target/release/t ~/.local/bin/t