Time Tracking App

Most of my development work originates from my Linux workstation.  I’ve done my share of Windows programming too, but all things being equal, I favor Linux.  Emacs is my editor and IDE and the bash shell is my most used tool.

So when I needed a utility to track hours I was spending on various freelance jobs, I decided to write my own.  One of the best ways to improve your coding skills is to continually solve problems. Creating small tools that not only enhance your productivity, but sharpen your skills is a great way to do this.  One of the reasons CLI apps are so useful is they can be easily wired to together with other small tools allowing you to quickly solve complex problems.  It’s the “do one thing and do it well” mentality.

When I’m in the middle of a project and need a tool, my first inclination is to write the tool in the language I’m currently working in (if possible).  Javascript wouldn’t have been my first choice for this sort of tool, however that was my current language at the time.  And javascript (node) turns out to be a suitable environment for CLI.

You can get the source here:

https://github.com/maitkin/timeclock.git

Quickstart

$ npm install -g
$ export TIMECLOCK_FILE=~/my-timeclock.db
$ timeclock --in
...time passes...
$ timeclock --out -c project-foobar
$ timeclock


Summary Report

         Sun   Mon   Tue   Wed   Thu   Fri   Sat   Total     Wage
Feb 10     -     - 10.02     -     -     -     -   10.02     0.00

February      10.02     0.00
Grand Total   10.02     0.00


 

Install the source using npm and define the TIMECLOCK_FILE environment variable to point to the full path where you wish to store the database file.

The above example will clock you in and out (with an optional category).  If no arguments are passed, the summary report will be printed.  If you want to include billings (earnings) in your reports, define your hourly wage by setting the environment variable TIMECLOCK_WAGE.

 

$ export TIMECLOCK_WAGE=75
$ timeclock

Summary Report

         Sun   Mon   Tue   Wed   Thu   Fri   Sat   Total     Wage
Feb 10     -     - 10.02     -     -     -     -   10.02   751.25

February      10.02   751.25
Grand Total   10.02   751.25

 

Synopsis


$ timeclock --help

Usage: timeclock [options]

Options:
  -f,  --file [file]           The file to use for the database
  -s, --summary-report         Print the summary report
  -d, --day-category-report    Print the current week category report
  -w, --week-category-report   Print the weekly category report
  -m, --month-category-report  Print the monthly category report
  -y, --year-category-report   Print the yearly category report
  -i  --in                     Clock in
  -o  --out                    Clock out
  -c  --category [category]    Use this category when clocking out
  -u  --current                Display the current (open) entry
  -h, --help                   output usage information

 

The app uses a text file database to track it’s entries.  You can either pass the file name in using the (-f) option, or even better is to set the environment variable TIMECLOCK_FILE to the full path of the file you want to use.  It will be created if it doesn’t exist.  There is a sample file (example.log) included with the repository that you can use to explore the interface:

 


$ timeclock -f example.log

Summary Report

         Sun   Mon   Tue   Wed   Thu   Fri   Sat   Total     Wage
Jul 30     -  7.37     -     -     -  8.72     -   16.08  1206.25
Aug 06  1.17  7.92  7.07  7.78  8.40  5.17     -   37.50  2812.50
Aug 13  1.97  9.23 10.33  9.42  7.00     -  2.10   40.05  3003.75
Aug 20  0.88  5.17  8.20  8.48  7.88  5.52  0.93   37.07  2780.00
Aug 27  4.77  7.70  7.18  8.33  7.00  2.97     -   37.95  2846.25
Sep 03     -  1.02  6.55  7.25  8.83  8.00     -   31.65  2373.75
Sep 10  0.53  6.27  8.58  7.95  0.00     -  0.05   23.38  1753.75
Apr 29     -     -     -     -     - 11.02     -   11.02   826.25
May 06     -     -  0.00     -     -     -     -    0.00     0.00
Feb 10     - 12.20 16.27     - 13.20 15.20     -   56.87  4265.00

February      56.87  4265.00
May           11.02   826.25
July           7.37   552.50
August       158.32 11873.75
September     58.00  4350.00
Grand Total  291.57 21867.50


 

By default, when no options are passed, the summary report is generated (above). The summary report shows a daily, weekly and monthly view of your logged hours.

The database file is text and you can simply edit it by hand if preferred:

$ cat example.log | head
Mon Jul 31 2017  08:43-16:05 projectZ
Fri Aug 04 2017  09:30-16:35 projectX	
Fri Aug 04 2017  19:13-20:35 projectX
Fri Aug 04 2017  22:06-22:22 projectX
Sun Aug 06 2017  17:55-19:05
Mon Aug 07 2017  09:25-16:03 projectX
Mon Aug 07 2017  18:08-19:03
Mon Aug 07 2017  20:40-21:02 projectZ
Tue Aug 08 2017  07:47-08:44 projectZ
Tue Aug 08 2017  09:30-15:37 projectY

 

The last field is the optional category which is passed in when clocking out (-o) using the (-c) option. Having categories allows you to view your time by project:

 

$ timeclock -f ./example.log -d

Mon
 4.28h projectX 
 7.92h projectY 

Tue
 4.28h projectX 
11.92h projectY 
 0.07h projectZ 

Thu
 4.28h projectX 
 8.92h projectY 

Fri
 4.28h projectX 
10.92h projectY 

 

There are also options to view project categories by week (-w), month (-m) and year (-y). To view the interval for the current (open) entry, use (-u):

 

$ timeclock -c

current	   8.49   373.55

 

Credit to cneumann for the original idea for this project. Pull requests are appreciated. There are still some missing features, but it works for my needs.

Cheers.