terminal-punch: Simple terminal-based time tracker

This is a package candidate release! Here you can preview how this package release will appear once published to the main package index (which can be accomplished via the 'maintain' link below). Please note that once a package has been published to the main package index it cannot be undone! Please consult the package uploading documentation for more information.

[maintain] [Publish]

terminal-punch is a convenient time tracker for the terminal.

For more information, see the README.

[Skip to Readme]


Versions 0.1, 0.1, 0.1.1, 0.1.3
Change log None available
Dependencies ansi-terminal (>=0.6), base (<5), filepath (>=1.1), text (>=1.2), time (>=1.9) [details]
License BSD-3-Clause
Copyright 2019 Emil Axelsson
Author Emil Axelsson
Maintainer 78emil@gmail.com
Category Utils
Home page https://github.com/emilaxelsson/terminal-punch
Bug tracker https://github.com/emilaxelsson/terminal-punch/issues
Source repo head: git clone https://github.com/emilaxelsson/terminal-punch.git
Uploaded by EmilAxelsson at 2019-01-22T21:50:53Z


Maintainer's Corner

Package maintainers

For package maintainers and hackage trustees

Readme for terminal-punch-0.1

[back to package description]


terminal-punch is a simple command-line time tracker.


cabal new-install terminal-punch


Despite its early stage, terminal-punch seems to work very reliably. It has a property-based test suite that covers most aspects of its time measurement.

Basic operation

Start by running punch in a terminal.

(Since the name of the executable is punch, I will use that name for the program in the remainder of the text.)

The program listens to the following keys:

Note that since the start/stop events are persisted in a log file (see below), punch doesn't need to be running in the background. It can just be opened temporarily for starting/stopping or viewing the summary. Personally, I use a keyboard shortcut to fire up a terminal with punch running in it.

By default, the summary will show the total time for the following periods:

Additional periods can be added by inserting period markers in the log file. We will explain how this is done later.

The log file

punch stores its time log in $HOME/.punch. Here is an example of what the file can look like:

Start 2019-01-17 12:29:13.80010349
Stop 2019-01-17 18:51:45.009426249
Start 2019-01-17 18:51:47.342016491
Stop 2019-01-17 19:10:45.566312123

Period "New job"
-- Started my new job
Start 2019-01-18 08:31:00
Stop 2019-01-18 13:40:00
Start 2019-01-18 16:16:00
Stop 2019-01-18 18:39:26.115783139

Each line must be one of:

The syntax for time stamps should be self-explanatory from the above example. Note that the eight-digit number denoting fractions of a second is optional.

punch requires the Start/Stop events to appear in alternating order. That is, there must not be a sequence consisting of two Start events without a Stop in between, and vice versa. Moreover, the time stamps must appear in increasing order. If the log gets corrupted, it can only be fixed by manual editing.

Working with the log file

Start/Stop lines are automatically appended to the log when an interval is started or stopped. This is the only thing punch ever does to the log; it will never change the existing content of the file. This means that it is completely safe to edit the log file between start/stop events.

Users are expected to manually edit the log in the following situations:

Period markers are used to measure time over longer periods. For example, inserting the line

Period "New job"

somewhere in the log tells punch to keep track of the total time from that point on. The result will be seen as an extra line in the summary:

New job    :  4 hours, 8 minutes
Last week  :  42 hours, 41 minutes
This week  :  9 hours, 43 minutes
Yesterday  :  8 hours, 3 minutes
Today      :  1 hours, 39 minutes

Any number of period markers can be inserted into the log.

Limitations and future work

punch doesn't currently have a way to distinguish between different kinds of work.

One idea for fixing this problem would be to support different "projects". Each project could have its own log file in the .punch/ directory. Some ideas regarding this approach: