#hoursctl

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.

#Installation

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

#Usage

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.

#Options

$ 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

	(always|auto|never)
		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

	<list>
		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)

<file>
	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-W25]
PT04H15M
PT00H15M
PT10H30M

[2022-W27]
2022-06-01 14:22 / 2022-06-02T15:00

[2022-W34]
2h50m
1h30m
1h

[2022-W37]
1:15
# put forks on tractor
0:05
1