time_track.tcl Command Line Time Tracking
In the spirit of TODO.TXT, this little Tcl script will handle tracking how much time you spend on tasks throughout the day. All records are stored in a plain text file so you’re not dependent on anyone else’s format.
This program is released under the BSD license.
If you already have MacPorts installed on your OS X system, you can install the latest version of Time-Track-CLI via the command:
sudo port install time-track-cli.
See http://macports.org for additional information on MacPorts.
Installation on *NIX systems should be pretty straightforward. The only dependencies are Tcl 8.5 or greater and the tcllib support library (specifically, the cmdline packet). If you’re running Ubuntu, you can install both of these using
apt-get install tcl8.5 tcllib
All data is currently stored in a single txt file in
The script itself is still somewhat rudimentary, and help is sparse. So here are some usage tips to get you started.
First, the script itself is called
time_track.tcl. All commands follow the format:
time_track.tcl <command> [options]
Most commands accept a
-help that will list all of the available options, defaults, etc.
Assuming you only need basic time tracking, you can use the program as follows:
$ ./time_track.tcl start hacking on a project $ ./time_track.tcl start hacking on another project $ ./time_track.tcl stop $ ./time_track.tcl summary Charges to <NONE> hacking on a project - 1 hour start hacking on another project - 1 hour --- Subtotal for <NONE> 2 hours For the day 2 hours
Using Task Codes
Let’s say you work for multiple clients, and you spend a portion of each day working on tasks for each of your clients. You can track time for each client as follows:
$ ./time_track.tcl start -code client_a hacking on project 1 $ ./time_track.tcl start -code client_a hacking on project 2 $ ./time_track.tcl start -code client_b fixing some bugs $ ./time_track.tcl start -code client_a more hacking on project 1 $ ./time_track.tcl stop $ ./time_track.tcl summary Charges to client_a hacking on project 2 - 18 minutes hacking on project 2 - 30 minutes more hacking on project 1 - 30 minutes --- Subtotal for client_a 1 hour, 18 minutes Charges to client_b fixing some bugs - 30 minutes --- Subtotal for client_b 30 minutes For the day 1 hour, 48 minutes
Lists all available commands along with a brief description.
The start command starts a new task. A new line is appended to the data file containing the starting time, along with a brief message describing the task. If a current task is running it will be stopped.
|| Explicitly set the starting time for the task. Defaults to
|| Set an associated code for the task. This is useful for grouping multiple tasks together into a single account and is used in summarization. This parameter also accepts an alias for a code. See the
The stop command stops the current task. The current time is used as the ending time for the task.
|| Explicitly set the stop time for the task. Defaults to
Summarizes all of the tasks for today and outputs a simple report detailing how long you spent on each task. Subtotals are provided for each task code as well as a total for the day.
|| The date to summarize. Defaults to
Lists all of the active task codes along with the date they were last used and the last description.
Lists all of the aliases for task codes.
One or more aliases may defined for each task code you use to track your work. Aliases are just another way of referring to the task code. If a task code corresponds to a length project or account number for timekeeping purposes, then you may define multiple aliases that are easier to remember. These aliases may be used anywhere you would otherwise use a task code.
Aliases are defined in the $HOME/.time_track/aliases.txt file. One alias may be defined per line, with each line having the following format:
<alias> = <code>
customer_a = account.number.for.customer.a customer_b = account.number.for.customer.b
Prints the currently active task along with the amount of time spent.
Cancels the currently active task, optionally resuming work on the previous task.
||Resume work on the previous active task.|
Prints the version number.
Time-Track-CLI supports the use of hook scripts to extend functionality. Hook scripts are small shell scripts executed at various stages within Time-Track-CLI. For example, the post-stop hook is executed whenever a task is stopped.
Currently the following hooks are supported:
- post-stop – Executed whenever a task is stopped.
Example hooks scripts are included in the source distribution. All examples end with the extension *.sample. The post-stop.sample script includes an example of how to post your tasks to Twitter.
To use the hook scripts, simple copy one of the *.sample scripts to
$(HOME)/.time_track, removing the *.sample extension. Then set the executable bits on the script.
Reporting Bugs and Requesting Features
Please report all bugs and feature requests via the Github issue tracker at http://github.com/dongola7/Time-Track-CLI/issues.