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:
apt-get install tcl8.5 tcllibOn Windows, I recommend downloading the excellent ActiveTcl distribution from the folks at ActiveState
All data is currently stored in a single txt file in $HOME/.time_track/time_track.txt.
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 hoursLet’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 minutesLists all available commands along with a brief description.
None
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.
| Option | Description |
|---|---|
-time |
Explicitly set the starting time for the task. Defaults to now. |
-code |
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 list-aliases command for more details on aliases. |
The stop command stops the current task. The current time is used as the ending time for the task.
| Option | Description |
|---|---|
-time |
Explicitly set the stop time for the task. Defaults to now. |
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.
| Option | Description |
|---|---|
-date |
The date to summarize. Defaults to today. |
Lists all of the active task codes along with the date they were last used and the last description.
None
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>For example:
customer_a = account.number.for.customer.a
customer_b = account.number.for.customer.bNone
Prints the currently active task along with the amount of time spent.
None
Cancels the currently active task, optionally resuming work on the previous task.
| Options | Description |
|---|---|
-resume |
Resume work on the previous active task. |
Prints the version number.
None
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.
Please report all bugs and feature requests via the Github issue tracker at http://github.com/dongola7/Time-Track-CLI/issues.