command-line program to manage your hours

9fa2d90 Add --edit

~u9000 pushed to ~u9000/hoursctl git

1 year, 5 months ago

#6 Add an “edit” option

~u9000 commented on hoursctl todo

1 year, 5 months ago


A command-line program to manage your hours. You list hours (for example, hours you've worked) in a text file and then hoursctl can show a tally for you. It’s designed to be easy to use, standards-compliant, and text-based.


If your distro gzips man pages, then run make install GZ=.gz. Otherwise, just do make install.


One of the primary goals of hoursctl is to understand as many time formats as it reasonably can, so you can enter your hours just-about however you like, and hoursctl will convert it into ISO-8601–format and process it from there. Really the only limitations are that you can’t use scientific/engineering notation, you have to write the number of hours if you’re also specifying the number of minutes (ie 0 hours 30 minutes instead of 30 minutes), and that hours and minutes have to be separated by at least one nonnumeric character.


$ hoursctl -h

usage: hours [-a|--all] [-c|--color (always|auto|never)] [-d|--debug]
             [-h|--help] [-w|--weeks|--week <list>] [<file>]

-a --all
	total the hours for all weeks

-c --color
	whether to output with color

		defaults to auto
-d --debug
	print debug messages

-e --edit
	edit <file> in $EDITOR and exit

-v --version
	print version number and exit

-w --weeks --week
	total the hours for the given week(s). defaults to most-recent week

		colon- or comma-separated list of weeks. weeks are in the format
		of [<YYYY>-]W<WW>, but feel free to enter them however you'd
		like (including ±<n> for forwards/backwards)

	hours file. defaults to ${XDG_DATA_HOME:-~/.local/share}/hoursctl/hours.
	if <file> is specified but does not exist, hoursctl checks whether it
	exists in ${XDG_DATA_HOME:-~/.local/share}/hoursctl (similar to how
	calendar(1) looks for files)

hoursctl does not yet have an ‘add’ option, so for now just use a text editor.

#File format

The hours file has one entry per line, and weeks are separated by ini-style headings. Comment lines begin with a hash (#). There aren’t any true inline comments, but hoursctl discards everything except the first two sets of digits when parsing basic entries.

Here’s an example:


2022-06-01 14:22 / 2022-06-02T15:00


# put forks on tractor