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.
alias a command Create or updates alias a for a particular command
aliases Shows list of all defined aliases
cleanup Cleanup and reorganize data file
init Initialize new data file
log Show activity log
log disable Disable activity log
log enable Enable activity log
status Display tracker status information
unalias a Remove alias a
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 project name Add new project with name "project name"
delete 23 Delete project with id 23
list List projects and their ids
rename 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.
cancel Cancel active tracker and dismiss time
change 23 Chance project assigned to an active tracker
comment comment Add "comment" to the current active tracker
pause Pause an active tracker
pause disable Disable tracking of pause times
pause enable Enable tracking of pause times
reset Reset time of active tracker
resume Resume tracker from paused project or from last project used
show Show tracked times for all projects
show 23 Show tracked times and some additional information for project 23
start 23 Start time tracking for project id 23
stop Stop active time tracking
switch 23 Switch a tracker to a new project by stopping it and starting a new
Aliases
Aliases defined in the data file
a add
c comment
ch change
d delete
l list
p pause
r resume
s show
st status
sw switch
Examples
--------
The following example should give you an impression of the default workflow.
First, a project named work will be created. Then a tracker will be started,
pause, resumed und finally stopped - by an alias that has been created.
This example shows also the reporting output for the tracked project time.
% tt add work
Created project 4: "work"
% tt start work
Tracker started for project 4: "work"
% tt
Tracking time in project 4: "work" for 00:01 (0.02 hours)
% tt pause
Paused tracker for project 4: "work" after 00:01 (0.02 hours)
% tt resume
Resumed tracker for project 4: "work" after pause of 00:01 (0.03 hours)
% tt alias stopit stop
Created alias stopit for command stop
% tt aliases
a add
c comment
ch change
d delete
l list
p pause
r resume
s show
st status
stopit stop
sw switch
% tt stopit
Tracker stopped for project 4: "work" after 00:00 (0.01 hours)
% tt show work
4 work
2019-05-28 09:45 - 09:46 00:01 (0.02 hours)
09:47 - 09:48 00:00 (0.01 hours) 0.03 hours total
Total time tracked: 0.03 hours
% tt unalias stopit
Removed alias stopit for stop
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 .tt.json ~/Dropbox/tt.json
3. ln -s ~/Dropbox/tt.json ~/.tt.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
==========
Code Meaning
-----+---------------------------------------------------------------------
0 OK
1 Python Version < 3.x
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
13 Not allowed to alter special project
20 Project's name or ID not specified when trying to start tracker
21 Tracker already started
22 No tracker found
23 Not allowed to start or stop tracker for special project
24 Tracker already paused
30 Alias or command not specified when adding alias
31 Invalid command when trying to add alias
32 Alias not found
42 Disabled in local configuration
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.