tt - Ubiquitous Time Tracking for Command Line Aficionados

Posted by Metamorphant on June 21, 2020

tl;dr

My attempt at scratching my time-tracking itch has yielded an open source tool that might prove useful for other command-line-savvy individuals. It’s called tt. tt has made my life easier, maybe it’ll do the same for you.

Time-tracking made me miserable

Some say that time is money, while others claim that money can’t buy you happiness, which would mean that time can’t buy you happiness. You might be inclined to disagree, especially if you’re in the consulting business, in which case you’ll probably have noticed a strong correlation between the two concepts: the less time you spend doing silly chores, such as tracking your working hours, the happier you are.

Conversely, you’ll end up being very miserable if you’re forced to use a slow, bloated, complex web interface to minutely track every working hour. Over time, this leads to lowered morale and listlessness, causing your colleagues and customers to avoid and reject you. This then throws you into a deep depression, out of which you’ll emerge alone, smelly, homeless, and very likely with a serious substance abuse issue.

I myself ended up on this slippery slope to perdition after almost a decade of using evey conceivable time-tracking tool: web-based interfaces from the beginnig of the web 2.0 era, cheap tabular, click-heavy spreadsheet implementations in the browser, plain old excel files on shared drives reachable only from within certain networks – they all made me put off time-tracking and invoice report generation to the latest possible point in time - usually the end of the month. I would then frustratedly gather all my post-it notes, go through the chats with my loved ones to find out when I left the office and browse through the Jira tickets I’d recently closed in a painful, patchy, sorrowful review of last month’s effort.

Needless to say this method, applied by around two thirds of all IT consultants I’ve encountered to date, is not only responsible for low morale and increased alcohol consumption. It also yields bad quality time-tracking reports with potentially omitted billable hours and otherwise error-ridden invoices.

My holy grail of time-tracking

After one of these extremely infuriating end-of-the-month time-tracking orgies, I paused and analysed the reasons for my deep-seated hatred and dread of all time-tracking tools – the perceived root cause of my procrastination. My conclusion was: these tools were living in their own ivory towers, the interfaces created by people who did not have to work with them every day. Not only were they not fun to use, but required 100% of my focus, thus costing me valuable time.

I then did some soul-searching: how could I make precise time-tracking part of my daily routine? I needed a tool that blended into the background, silently accompanying me through my workflow, staying out of the way, not making me pause, think and switch contexts. It would need to produce reports in a simple format for our company’s simple time-tracking Google Spreadsheet, as well as customer specific reports for invoicing purposes.

It sounded like the holy grail – elusive and unattainable.

I need a butler

I had to get more specific. My ideal solution was a butler-like system that one could interact with by issuing simple commands from anywhere, at any time, such as Amazon’s Echo (Alexa):

  • “Machine, I just started working on Customer X at 7:30”, add some more detailed information about that work item,
  • “Machine, I just had an entertaining white-board session with the business department” followed by
  • “Machine, I just stopped working on Customer X at 9:15” to finish the task.

Natural, organic, unobtrusive – something that could happen in parallel to the actual task execution, with minimal loss of focus.

Two things prevented me from investigating this specific option further: I don’t like getting 1984-ed by the likes of Google and Amazon with their proprietary, closed-source 24/7 listening devices. I also needed a bit more “haptic” feedback regarding the result of my commands: were they successful, erroneous, etc.?

Since I am an avid Linux command line user, and I always have a terminal at my fingertips, a command line interface (CLI) tool could also fit into my workflow perfectly and otherwise behave just as described above.

Enter ti

So I proceeded to scour the internet for a tool that would fit the mold. I needn’t look for long: Shrikant Sharat had already created ti (which was later forked and adopted by Richard Frenchuk), a simple Open Source application developed in Python that would store the results of the time-tracking commands in a JSON formatted file. It was released under the permissive MIT License, it was platform independent, it was small, it was easy to understand – I’d struck gold.

I immediately started using it as my daily driver, tracking time from any open terminal window. I’d usually open a time box in the morning. Throughout the day, I’d just add all the details required by the specific customer’s invoicing process to it, as they happened – all simple content-focused one-liners. In the afternoon, I’d close the time box just as I would leave the office. The only purely technical step required, was the manual synchronisation of the JSON database to Google Drive from time to time.

After playing around with ti for a while and setting it up from source code, I noticed a few use cases where the tool was not really delivering what I was requiring. I feared not, for the Holy Ghost of Libre Software spoketh to me. “Hear ye!”, it said, “Fork It!” And fork it I did.

ti++ = tt

I constantly improved the API, adding functionality where I felt it was lacking and removing features where it felt bloated. Over time, it drifted further and further from its origin, eventually warranting a rebranding.

I therefore renamed the tool to tt and published it to the Python Package Index, thus making it installable via pip and I’ve been a happy camper ever since.

What’s it feel like?

For a full reference of what tt is able to do, please consult tt’s documentation.

Installing tt is easiest via pip:

$ python3 -m pip install tt-time-tracker

You then need to set two system variables, to make sure you can interact with the tool reliably:

export EDITOR='vim'
export SHEET_FILE='/home/johnson/timesheets/time-entries.json'

To give you a basic idea of what it’s like to use, here’s a brief overview of my typical workflow on the commandline, adding time entries:

$ tt start my-project 14:15
$ tt note 'Got the business folk to talk to IT. Went well.'
$ tt stop 15:15

Once you’ve added time entries, you’ll want to also see them. Here is how to generate a report for a specific work item or customer:

$ ti report fav-customer 
Displaying all entries for fav-customer grouped by day:

weekday  |  date  |  start time  |  end time  |  break  |  total duration   |  description  | 
Wed | 2019-01-02 | 06:00 | 16:45 | 02:30 | 08:15 | Extended Spring config ; Serverspec improvement ; Test Framework improvements ;  ; 
Thu | 2019-01-03 | 06:00 | 17:00 | 03:00 | 08:00 | Reviews Daily board ; Serverspec support other team ; 
Fri | 2019-01-04 | 07:30 | 16:00 | 00:30 | 08:00 | Test framework implementation - Spring cfg and Infrastructure ; 
Mon | 2019-01-21 | 08:30 | 17:00 | 00:30 | 08:00 | Test framework: wrapping it up ; Dynamic values in property-files required ; 
Tue | 2019-01-22 | 06:00 | 17:00 | 02:30 | 08:30 | Whole day workshop day one: refinements, story defintion, backlog cleanup.

And here comes the pièce de résistance – calview. I noticed sometimes, I would forget to enter holidays or vacation days into the system. In order to gain the overview, I decided to build a rudimentary calendar month view, that shows all individual packages I worked on during one day. Here it what that looks like:

What else can I do?

This little tool has made my time-tracking workflow not just bearable, but unobtrusive and sometimes even fun. Because it is command-line based, it integrates seamlessly with a lot of other programs: generated reports can be opened as CSV files in Libre Office Sheets with a single command, one can filter within the results with grep, etc.

I will delve deeper into tips, tricks and integrations around tt in the next post.

Is it really that good?

After two and a half years of using ti/tt on a daily basis, I can actually say that it’s done wonders in my battle against time-tracking procrastination. tt tracks time without ever getting in the way of time-tracking.

Do you have similar issues? Just give tt a try! It might really work wonders for you too. At the very least, using tt makes you a better person. But only if you RTFM! first.

Post header background image by andreas160578 from Pixabay.

Contact us