Package: tt-time-tracker
tt - A command-line based time trackerttis a small stateful command line time tracking application
implemented in Python. Simple basic usage looks like this:$ tt start my-project 14:15
$ tt note 'Got the business folk to talk to IT. Went well.'
$ tt stop nowAlternatively you can skip the colon when entering times:$ tt start my-project 0915
$ tt stop 1020tl;drInstalling using pipWhat is tt?ttis a simple command line time tracker. It is based onti, by Shrikant Sharat and Trevor
Bekolay and is written in Python.tiis in turn inspired by bothtimed, and the elegantly simplet.As opposed to its predecessorti,ttis mostly aimed at cli versed IT
consultants or other professionals who need topreciselykeep track of
their time spent working on multiple projects and issue customer
invoices based on their entries.Logical structurettis made up of two main logical modules:the actual time tracking module, that handles creation and editing of time entries (the C and U inCRUD).the reporting module, which handles the evaluation of already entered time information (the R in CRUD).Time boxesttenables the user to record their effort in the form oftime segmentsortime boxes.Atime boxis defined by:a namea starting pointan end pointoptional notesExample:$ tt start my-project 14:15
$ tt note 'Twas an extremely difficult call we had this afternoon'
$ tt stop 18:00Stateful time box definitionAnother, somewhat hidden dimension is thecurrent date- or day -
which isimplicitlytoday, your machine's currentdate, unless
explicitly overriden by using the environment variableTT_CURRENT_DAY:$ export TT_CURRENT_DAY="2023-08-30" 
# note the ISO formatting
# any tt commands issued in between here and the unset command 
# will refer to the 30th of August 2023

$ tt start future-task 00:00
$ tt note "Hoverboarding isn't what it used to be"
$ tt note "Also, I'm probably sleeping right now"
$ tt stop 07:00

$ unset TT_CURRENT_DAYStatefulness++ for your convenienceIn addition to the impliedcurrent date,ttsaves the outcome of any
successful command you've issued in a centralised JSON file. This means
that there isonly one stateofttfor your entire user session. You
can start a time box in one terminal window, add notes to it in another
one and finalise the time box in a third terminal.The location of the time entry database can be specified via the
environment variableSHEET_FILE. The default location is~/.tt-sheet.json.To make your custom DB location persistent, just add the following line
to your~/.bashrcas demonstrated here:export SHEET_FILE=/home/johnson/timesheets/time-entries.jsonPlease consider backing up this file regularly, so as to avoid any
data loss.To correct erroneous entries, you can either edit this file
directly or, alternately, usett's built-ineditfunction.You can process the data from the time entry DB with any tool of your choosing.ttprovides you with some basic reporting that might or might
not make sense for your purpose.UsageAdding a new time box:$ tt start fav-customer 12:15
Started working on fav-customer at 12:15.

$ tt status
You have been working on fav-customer for about 2 hours, since 12:15;
It is now 14:12.

$ tt stop now
So you stopped working on fav-customer.startandstopcan take a time argument of the formHH:mm,HHmmor the keywordnowat
which to apply the action. They store the times normalized to GMT in the
database, taking into account the DST values for your timezone.Therefore beware when editing the timestamps in the DB file directly - this type of time
arithmetic gets brainfucky really quickly and youwillprobably cock it up!Enhance your time box with notes and tags:Thenoteandtagcommands only work if an active (open) time box
exists, i.e. if thestopcommand hasn't been invoked yet:$ tt note "implement new user authentication"In order to reduce boilerplate text when adding loads of notes to your timebox,
tt also allows you to edit the notes of your current timebox only. Do this with the commandectoredit-current-timebox, which will launch the editor you've selected (see next chapter on how to do that):$ tt ectTag your activity for added reportability:$ tt tag privateChange entries:By setting a default text editor (console or gui-based) in the
environment variableEDITOR, you can easily correct mistakes. Just add
the following line, referencing your favourite text editor to your~/.bashrcand enable fast time entry correction.$ export EDITOR=vim
$ tt editThis will open your time entry DB using the specified editor in the
handy YAML format. Once you save your changes and exit the file, the
changes will be persisted back into your SHEET_FILE.See your entries:logGet a log of the total time spent on each activity:$ tt logGet a log of the total time spent on each activity, filtered by activities started within a given time period:$ tt log 2023-11-13 2023-11-15T13:00:00Accepts datetimes in ISO8601 format. End datetime not required.csvGet a list of all your individual log entries in CSV format, so that they can be imported
into your favourite spreadsheet editor$ tt csv

$ tt csv | grep 2018-01 ### will show all entries you logged in January 2018

$ tt --no-color csv | grep 2018-01 &gt; /tmp/jan-2018.csv ;
libreoffice /tmp/jan-2018.csvThe last command allows you to break out of the console and takes you
into the realm of spreadsheets. The--no-colorparameter makes sure
that the terminal's color markup does not end up in your csv file.reportGet a report for your project, grouped and summed up by day:$ tt report customeur

$ tt report customeur | grep 2018-10

$ tt --no-color report customeur | grep 2018-10 > /tmp/oct-2018.csv ; libreoffice /tmp/oct-2018.csvSame trick applies here. Beware that the CSV separator is in this case
the pipe symbol|, since semicolons are used for concatenating all the
different note entries into one big note field per day.calviewDoublecheck your entries per month and gain an overview of your effort
throughout the month. No more blindspots.When calling calview with one parameter, the application assumes you
want to have the calendar view for the supplied month and thecurrent
year.$ tt calview 7Specifying a different year for calview is done like so:$ tt calview 1 2054This last command will show you the working days of January 2054.And here's some example output:CaveatsThere is no proper validation of time entries as of now:should your end time be before your starting time, this will be
reflected in your reporting.As of version 1.0.3, the end time needs to be after
the start time of the timebox.should the timeboxes defined for various projects overlap, this will
be reflected in your reporting.Installing using pipExecuting the following command should get you up and running:$ python3 -m pip install tt-time-trackerBefore you start using it, make sure you have your environment set up - the location of the time entry database and
the editor - by adding the appropriate environment variables to your~/.bashrcor similar.export EDITOR='vim'
export SHEET_FILE='/home/johnson/timesheets/time-entries.json'Make sure you replace the values with ones that make sense to you.Installing from sourceAfter having checked out the sources by cloning this repo, change into the new folder and execute the setup script.$ git clone git@github.com:dribnif/tt.git
$ cd tt/
$ python3 setup.py clean installAnd you're ready to roll.Now make sure you add the two export statements to your~/.bashrc, in order to have full control overtt.export SHEET_FILE='/home/johnson/timesheets/time-entries.json' 
export EDITOR='kate'Obviously: replace the values of the parameters with ones that make sense for you.DevelopingIf you merely want to test your code changes live, you don't really need to "install" the program on your system.
You can instead just execute the file tt-dev.py with the arguments of your choosing:$ ###assuming you are in the correct folder - the one where tt-dev.py is located
$ python3 tt-dev.py start my-awesome-project nowDevelopersRemolded intottby@dribnifBased ontioriginally created by Shrikant Sharat
(@sharat87), and maintained by
(@tbekolay).Further InformationFor more context on tt, feel free to read this blog posthttps://metamorphant.de/blog/posts/2020-06-21-tt-ubiquitous-time-tracking-for-command-line-aficionados/LicenseMIT LicenseChange overview1.1.1ect | edit-current-timeboxfix: UTC datetime was being displayed in the comment when editing the current timebox1.1.0ect | edit-current-timeboxnew command that allows you to edit the notes within your timebox from an
editor of your choice1.0.11logimprovement: allow the user to define a timebox for which to display logged activitiesreportimprovements: report all activities if none specified, also consider the value of TT_HOURS_PER_DAY
when coloring in the total amount of hours workedhelpupdates to reflect the new functionality that was added
other minor bugfixes
Most of the features contributed bychigozienri1.0.6calviewimprovement: show in progress timebox as well, assuming end-time to be "now"1.0.4calviewimprovement: show weekend (Saturday and Sunday) in matrix view, if time has been logged on weekends.
Otherwise default to 5 day, Monday to Friday week. Contributed bynedimAT.1.0.3as of this version, the end time of an entry must beafterthe start time of said entry