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.6 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
=====
To display a help message you can call "tt help".
It will provide you with an overview of the supported commands and how to use
tt to track your times in a single project or different projects.
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
help Display this help
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"
default 23 Set project with id 23 as default project
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"
undefault Unset the current default project settings
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 add 30[-50] 23 2019-03-14T09:46:26 [append] Add a pause of 30 minutes (or a random duration between 30 and 50 minutes) to the project 23's time period started on 2019-03-14 09:46:26. If "append" the recorded work time will not be reduced by the pause's duration. IMPORTANT: You cannot add a pause to a currently active tracker (resulting in the error message "Could not find time period"). First stop the active tracker and add the pause afterwards.
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
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
Hooks
Hooks are (shell) commands to be executed if a user uses particular commands
hook add start date Run the shell command "date" if the user uses "tt start ..."
hook del start Removes the hook command execute when "tt start ..." is used
hooks List all supported hooks and the current configuration
Summarizing
These commands display the time tracked in different ways.
csv 23 Show tracked times as CSV
show Show tracked times for all projects
show 23 Show tracked times and some additional information for project 23
tab 23 Show tracked times in a pretty table format
week Show a report of the time tracked in the current week
week 23 Show the time tracked for project 23 in the current week
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.
The first 2 steps necessary before you are able to track your time is to
init a new data file and to create a least one project to track times for.
We will add a project called "work". 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 init
Initializing new data file /Users/fallenbeck/.tt.json
Converted data file format from version 1 to version 6
% tt add work
Created project 1: "work"
% tt start work
Tracker started for project 1: "work"
% tt
Tracking time in project 1: "work" for 00:01 (0.02 hours)
% tt pause
Paused tracker for project 1: "work" after 00:01 (0.02 hours)
% tt resume
Resumed tracker for project 1: "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
Time tracker stopped for project 1: "work" after 00:00 (0.01 hours)
Total time tracked today in project 1: "work" is 00:01 (0.03 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
% tt start
You must specify a project id or set a default project
1 work
p Pause
% tt default work
Set project 1: "work" as default project
% tt start
Time tracker started for project 1: "work"
% tt stop
Time tracker stopped for project 1: "work" after 00:00 (0.00 hours)
Total time tracked today in project 1: "work" is 00:01 (0.03 hours)
% tt undefault
Removed 1: "work" as default project
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.
tt tab does not work for me
---------------------------
When printing the table I rely on Python's PrettyTable module. You can
install PrettyTable using pip3:
python3 -m pip install prettytable
Troubleshooting
===============
Error "Could not find time period" when trying to add pause
-----------------------------------------------------------
Pauses cannot be added to currently running tracking periods. Before you can add
a pause you first need to stop the current tracker.
Exit Codes
----------
Having a look at tt's exit code might be helpful in some cases. The following
exit codes are defined:
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
6 Could not import required python module
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
12 Project with given name or ID could not be found
13 Not allowed to alter special project
14 Default project not set
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
50 No comment given
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.