tt/README.md

69 lines
3.0 KiB
Markdown
Raw Normal View History

2021-12-06 10:47:19 +01:00
# tt
2021-12-17 12:30:31 +01:00
Simple command line time tracker for POSIX systems. \
Written by Patrick Lipka (patrick.lipka@emea.nec.com) \
2021-12-17 12:10:02 +01:00
This software is licensed under the BSD-2-clause license. Please see LICENSE for details.
## Dependencies
2021-12-17 12:32:09 +01:00
The program uses GNU Readline (https://tiswww.case.edu/php/chet/readline/rltop.html) for command completion and history. \
The Readline library is free software, distributed under the terms of the [GNU] General Public License as published by the Free Software Foundation, version 3 of the License. \
2021-12-17 13:09:36 +01:00
Packages are available on most Linux distributions and BSD systems as well as macOS. Depending on your OS you man need to also install a package like libreadline-dev to have access to the headers.
2021-12-17 12:27:04 +01:00
2021-12-17 13:09:36 +01:00
The program assumes POSIX functionalities as provided by unistd.h and a Unix file system layout. The best way to run it on Windows might be to install a Unix compatibility layer or use Windows' Subsystem for Linux.\
2021-12-17 12:27:04 +01:00
To compile the program you need a C++ compiler which supports the C++11 standard.
2021-12-17 13:09:36 +01:00
The program has been tested on the following systems:
2021-12-17 12:28:31 +01:00
* Debian Linux 5.10.70-1, GCC 10.2.1 20210110
* macOS 11.5.2, Apple clang 12.0.5
2021-12-17 12:10:02 +01:00
## Installation
2021-12-17 13:16:42 +01:00
### Makefile variables
2021-12-17 13:09:36 +01:00
The following variables can be used to configure the build:
* `CXX` - C++ compiler, defaults to `g++`
* `PREFIX` - install prefix, defaults to `/usr/local`
* `USER_NAME` - user name to be mentioned in monthly reports, defaults to `$USER`
* `TRACKING_DIR` - directory where tracking files are saved, defaults to `/home/$USER/track`
2021-12-17 13:16:42 +01:00
The user name and tracking directory can also be set after installation by modifying `$PREFIX/etc/tt.conf`
### Build command
The default install process is:
2021-12-17 13:17:57 +01:00
~~~~
USER_NAME="<Your full name>" make
sudo make install
~~~~
2021-12-17 13:16:42 +01:00
2021-12-17 13:29:00 +01:00
Note that there is no `/home` directory on macOS. You may want to set `TRACKING_DIR=/Users/$USER/track`.
2021-12-17 12:27:04 +01:00
2021-12-17 12:10:02 +01:00
## Settings
2021-12-17 13:29:00 +01:00
The file `$PREFIX/etc/tt.conf` has the format `key=value` and contains the following settings:
* `user_name` - user name to be mentioned in monthly reports
* `tracking_directory` - directory where tracking files are saved and loaded from
2021-12-17 13:16:42 +01:00
2021-12-17 12:10:02 +01:00
## Usage
2021-12-17 13:50:36 +01:00
The program `tt` does not take any command line arguments. Once launched, it provides a command prompt which supports TAB completion and a command history using the arrow keys. It can be exited by pressing CTRL-C (catches SIGINT).
At startup, the config file `$PREFIX/etc/tt.conf` is beeing read and tracking data is loaded from `tracking_directory` if available. In case there is no tracking data available for the current month, the project structures are loaded from the previous month's file. In case there is no data available, an empty project list is beeing set up.
The following commands are available:
2021-12-17 13:52:13 +01:00
#### `ls [<Project Name>]`
2021-12-17 13:50:36 +01:00
2021-12-17 13:52:13 +01:00
#### `np <Project Name>`
2021-12-17 13:50:36 +01:00
2021-12-17 13:52:13 +01:00
#### `nt [<Project Name>/]<Task Name>`
2021-12-17 13:50:36 +01:00
2021-12-17 13:52:13 +01:00
#### `rm [<Project Name>/]<Task Name>`
2021-12-17 13:50:36 +01:00
2021-12-17 13:52:13 +01:00
#### `re [<Project Name>/]<Task Name>`
2021-12-17 13:50:36 +01:00
2021-12-17 13:52:13 +01:00
#### `sp <Project Name>`
2021-12-17 13:50:36 +01:00
2021-12-17 13:52:13 +01:00
#### `st [<Project Name>/]<Task Name>`
2021-12-17 13:50:36 +01:00
2021-12-17 13:52:13 +01:00
#### `start <Project Name>/]<Task Name>`
2021-12-17 13:50:36 +01:00
2021-12-17 13:52:13 +01:00
#### `at [<Project Name>/]<Task Name>`
2021-12-17 13:50:36 +01:00
2021-12-17 13:52:13 +01:00
#### `rt [<Project Name>/]<Task Name>`
2021-12-17 13:50:36 +01:00
2021-12-17 13:52:13 +01:00
#### `report [<yyyy-mm>]`