tblancher's timetracker timekeeping system
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
Go to file
Trey Blancher abc8f09f20
Initial commit of Keyboard Maestro export of timetracker macros
5 years ago
.gitignore Initial .gitignore 5 years ago
README.md Initial README.md written and posted. 5 years ago
chug Minor modifications 5 years ago
do_process Added '--' to grep calls to protect patterns 5 years ago
month-pack.sh Initial timetracker commit 5 years ago
timetracker.kmmacros Initial commit of Keyboard Maestro export of timetracker macros 5 years ago
timetracker.py Initial timetracker commit 5 years ago
year-pack Minor modifications 5 years ago



tblancher's CLI-based time tracking system

This framework is what I use to keep track of my time, as I work. Only one task is allowed concurrently, so if I switch to another task, I must end the current task before proceeding. This is tracked in a log file following format:

log file format

2017-12-08 08:59:06:  Begin internal task 1
2017-12-08 09:10:55:  End   internal task 1
2017-12-08 09:10:56:  Begin internal task 2
2017-12-08 09:15:14:  End   internal task 2
2017-12-08 09:15:14:  Begin [Customer_1] task 1
2017-12-08 09:19:52:  End   [Customer_1] task 1
2017-12-08 09:19:52:  Begin [Customer_1] PDROP-0000000 incident-related task 1
2017-12-08 09:27:37:  End   [Customer_1] PDROP-0000000 incident-related task 1
2017-12-08 09:27:38:  Begin [Customer_2] task 2
2017-12-08 11:00:39:  End   [Customer_2] task 2
2017-12-08 11:00:40:  Begin [Customer_1] PDROP-0000000 incident-related task 2
2017-12-08 11:07:24:  End   [Customer_1] PDROP-0000000 incident-related task 2
2017-12-08 11:08:56:  Begin internal task 3
2017-12-08 16:55:43:  End   internal task 3

The timestamp is in most-to-least significant units, though any valid date and time should work (however, any other format is untested. BEWARE!). The separator between the timestamp and the Begin or End keywoards is : , literally a colon followed by two spaces. Anything else will break timetracker.py, and the rest of it will fall down. Each task must have a Begin and End line, or else the output of timetracker will not be correct. Too many begins or ends should be detected by timetracker.py. The name of the task is free form, and must be identical for the Begin and End (otherwise timetracker.py will think they're different tasks).

Certain strings have special meaning to timetracker.py. The customer name in square brackets specifies that the task is related to a specific customer, to make tallying in Clarizen more straightforward. These can be any string, but I think names containing spaces is untested. The names can be anything, so things like [Citi], [Wells_Fargo], or [CS_Support]. The square brackets will be stripped in the report. The other format with significance to timetracker.py is the incident number, e.g. PDROP-0012345. These will tally as a separate line item in the timetracker report.

timetracker.py usage

The timetracker.py script is the basis, it tallies the time for each task and then outputs a report on how much each task takes to complete. It takes as its argument one or more text files, the log files in the format above. It should only report one line item per task, regardless of how many times it appears in the log. The output looks like this:

timetracker output

[Customer_1] PDROP-0000000 incident-related task 1           465s        0hrs        7min     0.13hrs
[Customer_1] PDROP-0000000 incident-related task 2           404s        0hrs        6min     0.11hrs
[Customer_1] task 1                                          278s        0hrs        4min     0.08hrs
[Customer_2] task 2                                         5581s        1hrs       33min     1.55hrs
internal task 1                                              709s        0hrs       11min     0.20hrs
internal task 2                                              258s        0hrs        4min     0.07hrs
internal task 3                                            20807s        5hrs       46min     5.78hrs

Incident total:               0s    0.00hrs
Unnumbered total:         28502s    7.92hrs
Section total:            28502s    7.92hrs

Note to self: There is a problem here, the Incident total is off. For the other scripts, this total isn't used, which is why I've missed it.


This script filters the output of timetracker.py, giving each organization (in square brackets) its own section, with its own tallies. This is designed to be directly transferred to Clarizen manually. It calculates the time total for each organization/category, plus anything uncategorized. At the end it prints a grand total for the day, which should be used to cross-verify in Clarizen.

It takes as its argument a filename with the current date (date +%F format), or it assumes the current date log file.


This script is designed to be run on Mondays, after the previous week of log files have been generated and closed out. The standard Monday usage takes no arguments, it expects all log files to be processed to be in the current directory. It runs do_process once for each day of the previous week, cleanly skipping any log files which do not exist. It pauses after each day report is output, allowing the user to transfer the times manually to Clarizen.

chug takes a single optional argument, a week offset (in case chug is executed for log files further back than last week). This uses the GNU date functionality of calculating "last Monday." On Monday this will be "today - 7 days", but on the following Tuesday this will evaluate to "yesterday". If Monday is a holiday and you're entering your timesheets on Tuesday you can enter chug 1 and it should do the right thing. chug with no arguments is equivalent to chug 0.


timetracker.py and the related do_process and chug scripts are designed to have each day with its own YYYY-MM-DD.log file in the current, timetracker directory. Over time, the log files in this directory can become quite numerous and unwieldy. To help combat this, month-pack.sh takes all the log files from the previous month, adds them to a compressed tarball, and deletes them from the directory. It is designed to be run once all of the log files for the previous month have been processed.


In the same vein as month-pack.sh, year-pack.sh tars up all the monthly tarballs (named YYYY-MM.tar.xz), and puts them into a single YYYY.tar file. It is designed to be run in January when all of the previous December log files have been processed. All of the YYYY-MM.tar.xz files will be deleted once the YYYY.tar file is created.