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.