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.
You can get the source here:
$ 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
$ 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.