NAME

SYNOPSIS

  chronosquirrel [options] [taskname]

DESCRIPTION

chronosquirrel manages a set of krons stored in the kronlog file. kron blocks may be started or closed, and they are assigned to particular tasks. Current (open) and previous (closed) krons may be displayed.

chronosquirrel was designed to have a minimal impact on the system. There are only three files needed: chronosquirrel itself, the kronlog file (a regular file used to store time records), and a configuration file. No DBMS, no database files, and no nonstandard Perl modules are required.

This man page primarily describes the options required to use chronosquirrel. A very complete, detailed description of how to use chronosquirrel is provided in the Chronosquirrel User's Guide, available at https://www.waynemorrison.com/software/chronosquirrel-userguide.html.

GENERAL USE

Almost all the operations are invoked by running chronosquirrel with the appropriate option. However, if chronosquirrel is run without an option then the action take will depend on if a taskname was given on the command line. If taskname is specified, then one of the following will be done:

• If a time block is inactive, a new time block will be started. An inactive state exists if the final entry in the log file has an end state.
• If a time block is active, the current time block will be ended and a new time block will be started. An active state exists if the final entry in the log file has a start state.

OPTIONS

• -aliases
This option lists the aliases of the defined tasks. The alias-to-task mappings are given, with mappings for each alias.
• -all
This option is used in conjunction with -daily or -week and forces display of all defined tasks. By default, these options only display timing data on tasks that have been used during the day or week, depending on option chosen.
• -annotate [options] date time message
Add a user-specified annotation to the kronlog. This is a new comment added to the kronlog file.

If the first argument is not a date, then the annotation will be added in exactly the place the specified time requires.

The following options are recognized:

• -x: use the exact date, without rounding up to the nearest kron
• -p: "prettify" the annotation with some blank comment lines
• -s: add a separator line before the annotation
• -t: prefix the annotation with its timestamp

If the first argument is a date, then the annotation will be added immediately before the kron that precedes the given time.

The date argument can be in either the MM/DD or MM/DD/YY format.

The time argument can be in either the HH:MM or HH:MM:SS format.

The message is formed from the rest of the arguments. They are joined up into a space-separated string, which is then appended to "# ". This ensures that the message will be a comment.

• -cooked
This option turns on the cooked output mode. A lot of output processing is performed. The actual effect depends on what operations this is used with.
• -changekron <selection arguments> <new-value arguments>
This option modifies an existing kron from the kronlog. This is described in detail in the Editting an Existing Kron section.
• -day
• -daily
• -today
This option gives a summary of the tasks recorded for the current day. The time for each task is displayed, along with the daily totals.

When used with the -list option, each kron entry for the day is displayed, unsummarized.

These three option names are synonyms for the same operation.

• -deletekron taskname date time
This option deletes an existing kron from the kronlog. This is described in detail in the Deleting an Existing Kron section.
• -endkron
This option closes an open kron block.
• -fixit
This option is used in conjunction with the -health option and informs chronosquirrel that it should automatically save fixes to the kronlog. Specifying -fixit implies the -health option.
• -health
This option causes chronosquirrel to run checks on the configuration file and the kronlog file. These health checks are described in detail in the CHRONOSQUIRREL HEALTH section.
• -insertkron taskname date-time-arguments
This option inserts a new kron (or set of krons) into the kronlog. This is described in detail in the Inserting New Krons section.
• -kronlog file
This option specifies the name of the kronlog file to use. The default is .kronlog in the user's home directory.
• -lastweek
When the -lastweek option is given, the command will be run with a selection date of seven days prior to date of execution. This has the same effect as specifying the -select argument with a date of seven days before. If the other arguments work with -select, then they will work for -lastweek.

The -lastweek option calculates exactly seven days prior to date of execution. It does not worry about the day that starts a week, the day of the month, or the year; it only goes back exactly seven days.

The -lastweek option may not be used with the -select option.

• -listkrons
This option shows the kron entries in the kronlog. If raw output mode is used, the krons are given exactly as in the file. If rare output mode is used, the krons are given as in the file, except that the timestamps are translated from Epoch time to human-readable time.
• -rare
This option turns on the rare output mode. Some output processing is performed. The actual effect depends on what operations this is used with.
• -raw
This option turns on the raw output mode. Very little output processing is performed. The actual effect depends on what operations this is used with.
• -roll method
This option causes the kronlog file to be rolled. The method indicates the most recent point at which the file will be split into a roll file and the current kronlog file. The following are valid methods:

	year		most recent year boundary
	month		most recent month boundary
	week		most recent week boundary
	day		most recent day boundary
	MM/DD		specific month/day date
	MM/DD/YY		specific month/day/year date

• -seconds def|off|on
This option sets the value of the -seconds variable. The variable value must be either def, off, or on.
• -select date
This option is used in conjunction with the -day and -week options. It is used to select the day or week that will be displayed. If used with -day then information for the day specified will be displayed. (This option may also be used with -listkrons; this use is described in the next option description below.)

If used with -week, then information for the week in which that day lives will be displayed. (For purposes of chronosquirrel, weeks always start on Sundays.) This means that if a Tuesday's date is selected the week to be displayed will start with the Sunday two days before the selected Tuesday; it does not mean the seven days starting with the selected Tuesday

The date argument to this option can be in one of these forms: MM/DD, MM/DD/YY, DD/MM, or DD/MM/YY. The last two are assumed to be for non-USA users; this is determined by the value of the us-loc configuration value.

The -select option may not be used with the -lastweek option.

• -select selection-criteria
This option is used in conjunction with the -listkrons options. It is used to select the day or day range that will be displayed. It may also be used to select a specific task's entries to be displayed. The day/day range may be used together with the taskname or either may be used alone. (This option may also be used with -day and -week; these uses are described in the previous option description above.)

The full definition of selection-criteria is:

    date1-date2@taskname

If all these fields are given, all the tasks with the given taskname that were recorded between date1 and date2 are shown.

The date arguments can be in one of these forms: MM/DD, MM/DD/YY, DD/MM, or DD/MM/YY. The last two are assumed to be for non-USA users; this is determined by the value of the us-loc configuration value.

If date1 is given alone, a single date's entries will be displayed.

If entries from a range of dates should be displayed then date1 and date2, separated by a dash, must be given. date1 must come before date2.

If only a single task's entries should be displayed, then taskname is given, and it must be preceded by the '@' sign.

If used together, the date/date range must be given before the task name.

The -select option may not be used with the -lastweek option.

• -tasks
This option lists the tasks defined in .chronosquirrelrc, sorted alphabetically. The billable/nonbillable value and ordering number are shown for each task. If the -verbose option is given, then headers are given for each column.

The output mode determines how the billable column is shown:

• mode: billable/nonbillable
• raw: 1/0
• rare: billable/nonbillable
• cooked: yes/no
• -watch
• -clock
This option provides an active display of the status. This loops until killed, displaying the status as if chronosquirrel were called without any arguments. The status is displayed once every second. This option allows a constant, updating display of the status to be available. These two option names are synonyms for the same operation.

In order to keep as fresh a view of things as possible, the config file will be re-read periodically. If the seconds flag (provided by command-line arguments, config file, or the program default) is "def" or "on", then the config file is re-read every ten seconds. If the seconds flag is "off",

• -week
• -weekly
This option gives a summary of the tasks recorded for the current week. The time for each task is displayed, along with the daily totals. The week is defined to start on Sunday.

When used with the -list option, each kron entry for the week is displayed, unsummarized.

These two option names are synonyms for the same operation.

• -verbose
This option displays verbose information.
• -Version
Display the version information for chronosquirrel.
• -help
Display a help message.

FILES

~/.kronlog - Time records are stored in this file.

~/.kronlog.bak - Time records are stored in this file. Up to 100 backup files can be created, with a numeric suffix -- ~/.kronlog.bak.00 to ~/.kronlog.bak.99. If the logfile has a different name than ~/.kronlog, then that will be used as the basename.

~/.kronlog.tmp - Temporary file used when saving fixed log files. If the logfile has a different name than ~/.kronlog, then that will be used as the basename.

SEE ALSO

AUTHOR

LICENSE

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0