tt is a time tracker for the command line.
Introduction
============
I looked around for a time tracking tool that can be used from the command line
independent from the computer I use. I did not find any solution I wanted to
use over a longer period.
That said, tt is tailored for my (very basic) needs: To keep an eye on my
working hours when I am in home office and to track time whenever I work on one
of my side projects. Until now, I used a macOS-only solution called Tyme2. I
liked it a lot and wanted to have something comparable on the shell using an
open and human-readable file format.
Installation
============
I tried to keep tt as simple as possible. It has been written in Python 3 but
does not have any external dependencies so far. This makes the installation
easy as long as you have Python 3 (not 2!) installed on your machine:
1. Clone the project or download it as an archive and unpack it
2. Move the tt file to some location existing in your PATH
(or create a symlink)
3. If you don't like the name: rename the file or create a symlink
Usage
=====
Generic commands
Commands to initialize tt and perform management tasks.
cleanup/c Cleanup and reorganize data file
init Initialize new data file
status/st Display tracker status information
Projects
Before you can start a tracker you need to create a project to which this tracker is assigned. These commands allow you to add, delete and manage existing projects.
add/a project name Add new project with name "project name"
delete/d 23 Delete project with id 23
list/l List projects and their ids
rename/r 23 new name Rename project with ID 23 to "new name"
Tracking
These commands allow to start and stop trackers as well as displaying tracked times in existing projects.
show/s Show tracked times for all projects
show/s 23 Show tracked times and some additional information for project 23
start 23 Starts time tracking for project id 23
stop Stops active time tracking
Frequently Asked Questions
==========================
I don't like the name tt
------------------------
You are free to rename it or create a symlink with some name you really like.
This should not cause any problems.
I don't like the data file's name
---------------------------------
You can change the program and specify a data file name you like. It is open
source software for exactly that reason (and others...)
I found a bug!
--------------
Great. I would be happy to hear from you. You can either contact me via
GitHub or - even better - you can fix the bug and send a pull request that
allows me to merge your fix into the main branch.
I want to use tt on several computers, how can I synchronize the data?
----------------------------------------------------------------------
Actually, this is also my use case. I initialize a new datafile on one
of my computers, move it to my Dropbox folder and create a symlink in my
home directory pointing to this file. I create this symlink on all machines
where I want to use tt:
1. tt init
2. mv .tymetracker.json ~/Dropbox/tymetracker.json
3. ln -s ~/Dropbox/tymetracker.json ~/.tymetracker.json
Whenever you modify your local data it is synced to the other machines.
Yes, you can use other synchronization tools as well.
I want to use my phone as time tracking device. Is there an app?
----------------------------------------------------------------
Hipster.
But you can create a virtual machine at Amazon, install your favorite
operating system and run tt via SSH. Or you write your own app (see next
question).
What file format is used to store the data?
-------------------------------------------
tt stores it's data in plain text and in human readable JSON format. tt
does not compress the file and even uses a very human-friendly formatting
to make sure that everyone can review and modify its data.
But beware! If you mess up the file, tt will not work until you fix the
problem or re-initialize tt (via tt init).
The usual location of the hidden data file is right in your home: ~/.tt.json
Have a look at the tt-sample.json file to get an impression.
What does "cleanup and reorganize" mean?
----------------------------------------
During the use of tt projects may be created and deleted. However, the ID
assigned to a new project is always the successor of the last ID assigned.
When deleting an earlier project there might be holes and the project IDs
are not consecutive anymore. When calling the cleanup function new IDs
are assigned to the projects eliminating these holes and re-establish a
consecutive list of IDs.
Exit Codes
==========
| Exit Code | Meaning |
| ---------:|:------- |
| 0 | OK |
| 1 | Python Version < 3.x used to run `tt` |
| 2 | Data file should be initialized but does already exist |
| 3 | Data file not found |
| 4 | Other exception while trying to read data file |
| 5 | Could not read data from data file |
| 7 | Exception while saving/writing data to data file |
| 10 | Project's name or ID not specified when trying to add a new project |
| 11 | Project's name or ID not specified when trying to delete/rename p. |
| 12 | Project with given name or ID could not be found |
| 20 | Project's name or ID not specified when trying to start tracker |
| 21 | Tracker already started |
Contact
=======
If you have any questions, please feel free to contact me using GitHub.
If you have a great idea what I should build right into tt, let my know by
opening a pull request.
Don't hesitate to contact me. Really.