cavejay / tt Goto Github PK

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.