Timetrace

<h1>:alarm_clock: timetrace <a href="https://circleci.com/gh/dominikbraun/timetrace"><img src="https://circleci.com/gh/dominikbraun/timetrace.svg?style=shield"></a> <a href="https://www.codefactor.io/repository/github/dominikbraun/timetrace"><img src="https://www.codefactor.io/repository/github/dominikbraun/timetrace/badge" /></a> <a href="https://github.com/dominikbraun/timetrace/releases"><img src="https://img.shields.io/github/v/release/dominikbraun/timetrace?sort=semver"></a> <a href="LICENSE"><img src="https://img.shields.io/badge/license-Apache--2.0-brightgreen"></a> </h1>

timetrace is a simple CLI for tracking your working time.

:fire: New: Add tags for records
:fire: New: Use decimal hours when displaying durations
:fire: New: Restore records when restoring the associated project
:fire: New: Support for per-project configuration

---

• Installation
  • Homebrew
  • Snap
  • AUR
  • Scoop
  • Docker
  • Binary
• Usage example
  • Project modules
• Shell integration
  • Starship
• Command reference
  • Start tracking
  • Print the tracking status
  • Stop tracking
  • Create a project
  • Create a record
  • Get a project
  • Get a record
  • List all projects
  • List all records from a date
  • Edit a project
  • Edit a record
  • Delete a project
  • Delete a record
  • Generate a report [beta]
  • Print version information
• Configuration
  • Prefer 12-hour clock for storing records
  • Prefer decimal hours for status and reports
  • Set your preferred editor
  • Configure defaults for projects
• Credits

---

Installation

Homebrew

brew tap dominikbraun/timetrace
brew install timetrace

Snap

sudo snap install timetrace --edge --devmode

AUR

yay -S timetrace-bin

Scoop

scoop bucket add <name> https://github.com/Br1ght0ne/scoop-bucket
scoop install timetrace

Docker

The timetrace Docker image stores all data in the /data directory. To persist this data on disk, you should create a bind mount or named volume like so:

docker container run -v my-volume:/data dominikbraun/timetrace version

Binary

Download the latest release and extract the binary into a directory like /usr/local/bin or C:\Program Files\timetrace. Make sure the directory is in the PATH variable.

Usage example

First, create a project you're working for:

timetrace create project make-coffee

Once the project is created, you're able to track work on that project.

timetrace start make-coffee

You can obtain your currently worked time using timetrace status. When you've finished your work, stop tracking:

timetrace stop

Project modules

To refine what part of a project you're working on, timetrace supports project modules. These are the exact same thing as normal projects, except that they have a key in the form <module>@<project>.

Creating a grind-beans module for the make-coffee project is simple:

timetrace create project grind-beans@make-coffee

The new module will be listed as part of the make-coffee project:

timetrace list projects
+-----+-------------+-------------+
|  #  |     KEY     |   MODULES   |
+-----+-------------+-------------+
|   1 | make-coffee | grind-beans |
+-----+-------------+-------------+

When filtering by projects, for example with timetrace list records -p make-coffee today, the modules of that project will be included.

Shell integration

Starship

To integrate timetrace into Starship, add the following lines to $HOME/.config/starship.toml:

[custom.timetrace]
command = """ timetrace status --format "Current project: {project} - Worked today: {trackedTimeToday}" """
when = "timetrace status"
shell = "sh"

You can find a list of available formatting variables in the status reference.

Command reference

Start tracking

Syntax:

timetrace start <PROJECT KEY> [+TAG1, +TAG2, ...]

Arguments:

| Argument | Description | | ------------------- | -------------------------------------------- | | PROJECT KEY | The key of the project. | | +TAG1, +TAG2, ... | One or more optional tags starting with +. |

Flags:

| Flag | Short | Description | | ---------------- | ----- | ---------------------------------------------------------------------------------------------------------- | | --billable | -b | Mark the record as billable. | | --non-billable | | Mark the record as non-billable, even if the project is billable by default. |

Example:

Start working on a project called make-coffee and mark it as billable:

timetrace start --billable make-coffee

Start working on the make-coffee project and add two tags:

timetrace start make-coffee +espresso +morning

Print the tracking status

Syntax:

timetrace status

Flags:

| Flag | Short | Description | | ---------- | ----- | ------------------------------------------------------------- | | --format | -f | Display the status in a custom format (see below). | | --output | -o | Display the status in a specific output. Valid values: json |

Formatting variables:

The names of the formatting variables are the same as the JSON keys printed by --output json.

| Variable | Description | | ---------------------- | ---------------------------------------- | | {project} | The key of the current project. | | {trackedTimeCurrent} | The time tracked for the current record. | | {trackedTimeToday} | The time tracked today. | | {breakTimeToday} | The break time since the first record. |

Example:

Print the current tracking status:

timetrace status
+-------------------+----------------------+----------------+
|  CURRENT PROJECT  |  WORKED SINCE START  |  WORKED TODAY  |
+-------------------+----------------------+----------------+
| make-coffee       | 1h 15min             | 4h 30min       |
+-------------------+----------------------+----------------+

Print the current project and the total working time as a custom string. Given the example above, the output will be Current project: make-coffee - Worked today: 3h 30min.

timetrace status --format "Current project: {project} - Worked today: {trackedTimeToday}"

Print the status as JSON:

timetrace status -o json

The output will look as follows:

{
  "project": "web-store",
  "trackedTimeCurrent": "1h 45min",
  "trackedTimeToday": "7h 30min",
  "breakTimeToday": "0h 30min"
}

Stop tracking

Syntax:

timetrace stop

Example:

Stop working on your current project:

timetrace stop

Create a project

Syntax:

timetrace create project <KEY>

Arguments:

| Argument | Description | | -------- | ---------------------- | | KEY | An unique project key. |

Example:

Create a project called make-coffee:

timetrace create project make-coffee

Create a record

:warning: You shouldn't use this command for normal tracking but only for belated records.

Syntax:

timetrace create record <PROJECT KEY> {<YYYY-MM-DD>|today|yesterday} <HH:MM> <HH:MM>

Arguments:

| Argument | Description | | ------------- | -------------------------------------------------------------------------------- | | PROJECT KEY | The project key the record should be created for. | | YYYY-MM-DD | The date the record should be created for. Alternatively today or yesterday. | | HH:MM | The start time of the record. | | HH:MM | The end time of the record. |

Example:

Create a record for the make-coffee project today from 07:00 to 08:30:

timetrace create record make-coffee today 07:00 08:30

Get a project

Syntax:

timetrace get project <KEY>

Arguments:

| Argument | Description | | -------- | ---------------- | | KEY | The project key. |

Example:

Display a project called make-coffee:

timetrace get project make-coffee

Get a record

Syntax:

timetrace get record <YYYY-MM-DD-HH-MM>

Arguments:

| Argument | Description | | ------------------ | ------------------------------------- | | YYYY-MM-DD-HH-MM | The start time of the desired record. |

Example:

By default, records can be accessed using the 24-hour format, meaning 3:00 PM is 15. Display