thefenriswolf/ttt

Time Tracker Tool written in Golang

ttt

ttt is a cli time tracker tool written in GoLang, using a plain text file as it’s database.

Table of Contents

• ttt
• Installation
  • Via Go
  • Manual
• Usage
  • Getting started
  • Create a Journal File
  • Edit Journal settings
  • Organize and clean the database
  • Print Reports
  • Export Reports as PDF
  • Plot reports (NOT IMPLEMENTED YET)
  • Print help
• Credits
  • Dependencies
  • Similar Projects
• License
• The story behind this program

Installation

Via Go

go get github.com/thefenriswolf/ttt

Manual

Make

git clone https://github.com/thefenriswolf/ttt.git
cd ttt
make PLATTFORM # linux, osx, windows

sudo mv ttt_PLATTFORM_amd64 /usr/local/bin/ttt # optional

Nix

git clone https://github.com/thefenriswolf/ttt.git
cd ttt
nix-shell shell.nix
nix-build

Usage

Getting started

Create a database file, this is always a CSV file. !Currently you can’t change field order at runtime! This may be implemented in the future.

The following defaults apply:

• delimiter: ’ ’ (single space)
• comment: #
• date format: DD.MM.YYYY
• time format: HHMM

As you can tell from the example database below, the entries don’t have to be in chronological order. ttt will sort them and group them at runtime.

# date startTime endTime Activity

20.09.2023 1400 1700 $Jobname
20.12.2023 1400 1700 $Jobname
20.09.2023 1400 1700 $Jobname
20.07.2023 1400 1700 $Jobname
20.01.2023 1400 1700 $Jobname

Create a Journal File

ttt will create a template file at the current directory.

ttt init

Edit Journal settings

The header of your journal file contains setting fields.

Here you can set things like:

• hours: your weekly workhours
• delimiter: By default ttt uses a single space ’ ’
• datefmt: By default ttt uses DD.MM.YYYY
• timefmt: By default ttt uses HHMM

Organize and clean the database

ttt -f somefile.csv print >> newfile.csv

Prints your file to stdout after sorting it and removing empty lines.

Print Reports

ttt -f somefile.csv report

Prints a worktime report to stdout.

Example

[...]

20.01.2023 1400 1700 Job
20.02.2023 1400 1700 Job
20.03.2023 1400 1700 Job
20.04.2023 1400 1700 Job
20.05.2023 1400 1700 Job
20.06.2023 1400 1700 Job
20.07.2023 1400 1700 Job
20.08.2023 1400 1700 Job
20.09.2023 1400 1700 Job

[...]

By week

This is the default option.

ttt -f somefile.csv report week

Example

[...]

20.01.2023: 3h0m0s
20.01.2023: 3h0m0s
20.01.2023: 3h0m0s
20.01.2023: 3h0m0s
20.01.2023: 3h0m0s
20.01.2023: 3h0m0s
20.01.2023: 3h0m0s
20.01.2023: 3h0m0s
20.01.2023: 3h0m0s
20.01.2023: 3h0m0s
20.01.2023: 3h0m0s
20.01.2023: 3h0m0s
20.01.2023: 3h0m0s
20.01.2023: 3h0m0s
=========================
Summary KW3:
-------------------------
Weekly sum: 42h0m0s
Weekly overtime: 12h0m0s
=========================

[...]

By month

ttt -f somefile.csv report month

Example

[...]

20.12.2023: 3h0m0s
20.12.2023: 3h0m0s
20.12.2023: 3h0m0s
20.12.2023: 3h0m0s
20.12.2023: 3h0m0s
=========================
Summary of December:
-------------------------
Monthly sum: 15h0m0s

[...]

By year (NOT IMPLEMENTED YET)

ttt -f somefile.csv report year

Export Reports as PDF

ttt -f somefile.csv export

Prints a worktime report to a PDF file in your current directory.

By week

This is the default option.

ttt -f somefile.csv export week

By month

ttt -f somefile.csv export month

Plot reports (NOT IMPLEMENTED YET)

ttt -f somefile.csv graph

Prints a graph of your worktime to stdout

By month

This is the default option

ttt -f somefile.csv graph month

By year

ttt -f somefile.csv graph year

Print help

ttt --help

Credits

Dependencies

ttt depends on the following projects:

• Marcel van Lohuizen’s unique package
• urfave’s cli package
• pterm

Similar Projects

• ledger-cli the main inspiration for this project.
  • yes, you can track time with ledger see here

License

ttt is BSD Clause 3 licensed.

The story behind this program

ttt has been created to solve a very specific problem of mine:

You see I want to track my workhours, but I can’t bring my laptop with me to work. Of course the company I work for has it’s own fancy web-based worktime recording system. It does sophisticated reports, keeps track of your days off and even handles day off requests.

But I found it to be unreliable, at least once a month it fails to record my clock-in or clock-out. This can only be retroactively filled in by someone with admin privileges, which I don’t have. So in theory a nefarious employer could ask the admin to manipulate the database in their favor.

Thus I have my own offsite recordings, in the past I used to use an app on my phone for this. I would then export my records as a CSV file and process it on my computer.

This worked just fine until the app developer got greedy and locked the export button behind a 35€ (or 0.99€/mo) paywall!

At that time I was already using ledger-cli for my finances and ledger can also do time tracking. But writing ledger files by hand on a tiny smartphone screen is tedious.

Yes you can prepopulate the file with blank entries on a computer and just fill in the time on the phone or copy and paste a template every time.

Trust me I tried both methods.

The blank entries method makes you search for the current date for a while and the copy and paste method falls apart when you see how bad precise text selection works on a phone.

For the uninitiated, a ledger time record looks like this:

i 2023/12/20 05:30:00 Work:$Job
o 2023/12/20 14:00:00

Two lines, not too bad you’d think, what’s the big deal you’d think.

Well let me tell you, those 2 lines per day add up.

Let’s do some quick math:

• The usual work week for most people (at least where I live) consist of 5 workdays.
• There are 52 weeks in a year if we don’t account for days off.
• We need 2 lines per record, but realistically you want a blank line after every record to introduce at least a minimum of readability.

5 days per week * 52 weeks per year * 3 lines per entry = 780 lines!

You see, by December i was scrolling quite a bit to get to the bottom of a file. Now of course you could combat that problem by creating a new file every month but that method just does not scale if you want to calculate your overtime at the end of the year.

So I searched around for a while for project that could do the same job but with a quicker syntax. Most programs command syntax (like timewarrior) require you to be on a computer to use the program effectively.

This made me think if I couldn’t write my own program, that fit my needs perfectly, bear in mind that I am not a programmer and I also don’t play one on TV. The best I could do were:

• nix for my home-manager and NixOS configs
• bash scripts that failed in spectacular ways with more bugs than features
• python image manipulation scripts I had to write for University
• and R statistics scripts, also for University

So here we are, I made a program that barely has enough features to be useful to me. I chose GoLang because I wanted it to be statically compiled and sort of fast (ttt spits out reports in ~20ms).