Chronosquirrel User's Guide

version 2.6


chronosquirrel is a time-tracking program, keeping track of clock-time spent on user-defined tasks.




  1. Introduction
2. General Use
2.1. Defining Tasks
2.2. Tracking Task Times
2.3. Stopping Time Tracking
2.4. Displaying Status
2.5. Listing Time Tracking
3. Output Modes
  4. Configuration File
4.1. Task Definitions
4.2. Task Name Aliases
4.3. Kronlog File
4.4. Seconds-Display Flag
4.5. US-Location Flag
4.6. Example .chronosquirrelrc
  5. Managing Kronlog Files
5.1. Inserting New Krons
5.2. Editting an Existing Kron
5.3. Deleting an Existing Kron
5.4. Manual Editting of an Existing Kron
5.5. Rolling Kronlog Files
5.6. Annotating Kronlog Files
5.6.1. Format of Annotating Commands
5.6.2. Examples of Annotating Commands
5.6.3. Details of Annotation Placings
  6. Chronosquirrel Health
6.1. Configuration File Validation
6.2. Kronlog File Validation
6.3. Health Files
7. Options
8. Files
9. Credits and License
9.1. Document Version
9.2. License Information
 


1. INTRODUCTION

chronosquirrel is a time-tracking program, that is based on tracking the clock-time spent on particular tasks. It manages krons, which are records of time blocks used for a particular task. Task start time and task end time are recorded, so that current tasks, as well as tasks from times past, may be tracked and reported. Since chronosquirrel was originally written to manage time charged to clients, it separates the concept of billable and nonbillable time.

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 User's Guide is a very complete, detailed description of how to use chronosquirrel. However, to start off it may be easier to just copy the example configuration file from Defining Tasks, run "chronosquirrel testing", and start playing with the various options.



2. GENERAL USE

At a high-level, the arguments to chronosquirrel define the actions that may be taken. All of chronosquirrel's functioning is self-contained; there are no other programs required to use it. There are two other files, but those hold data.

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:

This section explains some basic chronosquirrel concepts and describes how to use the command. The example tasks defined in the Defining Tasks subsection will be used in examples throughout the rest of this section.

If an option and a taskname are not specified on the command line, then a status entry will be displayed. The active taskname and the amount of time spent on the task will be displayed. If there isn't an active task, then Off Clock will be shown. The time elapsed for that task (or in the Off Clock state) will be displayed. It is possible, though not advised, to record time for a point in the future. If this is done, then the status message will also contain the time until that future task starts.

2.1. Defining Tasks

The first step in using chronosquirrel is to define a list of tasks that it will track. The tasks may be work projects, activities, whatever you want to keep track of the time you spend doing.

Tasks definitions are stored in the chronosquirrel configuration file. By default, this is .chronosquirrelrc in the user's home directory.

Each task has the following set of associated characteristics:

Example tasks:

	development	billable	dev,coding		1
	testing		billable	tst			3
	curling		nonbillable	(none)			2
	breaks		nonbillable	lunch,coffee,tea	8
Example .chronosquirrelrc file for these tasks:

	task "development"	billable	active		1
	task "testing"		billable	active		3
	task "curling"		nonbillable	active		2
	task "breaks"		nonbillable	active		8
	task "training"		billable	inactive	5

	alias "development"	"dev", "coding"
	alias "testing"		"tst"
	alias "breaks"		"lunch", "coffee", "tea"

2.2. Tracking Task Times

Once tasks are defined, they may be passed to chronosquirrel to initiate tracking the time of that task. Tracking is initiated by running chronosquirrel with the name of the task as the command argument.

Examples:

	$ chronosquirrel development
	$ chronosquirrel dev
	$ chronosquirrel tea
Running chronosquirrel without any arguments will give the current state. This will be either Off Clock, or with the name of the active task and the amount of time this kron block has been active.

Examples:

	$ chronosquirrel
	Off Clock
	$ chronosquirrel dev
		... over two hours pass ...
	$ chronosquirrel
	development:  02:17:51

2.3. Stopping Time Tracking

Time tracking of a task can be stopped in two ways. First, running chronosquirrel with the -end option will halt time tracking, leaving chronosquirrel and its kron log in the "Off Clock" state.

Example:

	$ chronosquirrel development
		... time passes ...
	$ chronosquirrel -end
Second, running chronosquirrel with the name of another task will stop tracking the active task and start tracking the newly named task.

Example:

	$ chronosquirrel development
		... time passes ...
	$ chronosquirrel curling
A kron block will cover a single day at the most. If a start time and its corresponding end time are on different days, then the kron block will be split into a set of kron blocks. The same amount of time will be covered for that one task, but internally it will be stored as a set of separate instances.

2.4. Displaying Status

There are three ways of displaying tracked time with chronosquirrel. Several options may be used to modify the output displayed.

The first is the current status -- active task and time currently spent on the task. If the -verbose option is given and the current state is "Off Clock", then information about the previous task will also be given.

The second is a summary of the tracked time for the current day. This summarizes only the tasks that have had time charged to them that day. An indicator is also included for those tasks that are billable. Several daily totals are also included.

The third provides a daily summary for the current week, starting on the most recent Sunday. This does not include an indicator for billable tasks. Several weekly totals are also included.

Example:

	$ chronosquirrel
	Off Clock:  3:20:12

	$ chronosquirrel
	dev:  2:15:01

	$ chronosquirrel -verbose
	Off Clock:  3:20:12; last task was "development" for 1:01:15

	$ chronosquirrel -today
	development  :  2:51:20         $
	testing      :  5:40:00         $
	curling      :  1:16:56

	Billable     :  8:31:20
	Nonbillable  :  1:16:56
	Total        :  9:48:16

	$ chronosquirrel -week
	Task             Sun     Mon     Tue     Wed     Thu     Fri     Sat	Totals
	development              5:01    3:51    0:45                            9:37
	testing                  3:30    4:20                                    7:50
	curling                                  1:00                            1:00

        Billable                 8:31    8:11    0:45                           17:27
        Nonbillable                              1:00                            1:00
        Total                    8:31    8:11    1:45                           18:27
Using the -verbose and -week options together will fill out the empty slots with "0:00".

A related form of the first method -- display of the current status -- is provided by the watch option. This form gives an active display of the status. chronosquirrel 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.

2.5. Listing Time Tracking

The -listkrons command displays the entries in the kronlog file. This is a more low-level display of the time, as it is showing the unsummarized records. Some output formatting may be done, depending on the output mode. (See Output Modes below.) Each entry in the log file is referred to as a kron, and each start/end pair of records is a kron block.

In raw mode, the kronlog entries are given almost exactly as they appear in the file. However, there are two minor modifications to improve readability. First, comment separators are inserted in the output to separate one day's entries from the others. Second, the data in all the columns are lined up.

In rare mode, the kronlog entries are given mostly as they appear in the file. However, blank lines are inserted in the output to separate one day's entries from the others. Also, each entry's timestamp is converted from the Epoch Time number to a human-readable time/date string.

In cooked mode, the kronlog entries are condensed into a single line per kron block. The starting time is at the beginning of the line (for sorting purposes), followed by the task name, the ending time, and the "hours:minutes" form of the length of the kron block. If the ending time is not given, then that task is currently active. Both times are given in human-readable format.

Cooked mode is the default for chronosquirrel. "chronosquirrel -listkrons" gives the same output as "chronosquirrel -listkrons -cooked", so only the second form is shown in the examples below.

Examples:

	$ chronosquirrel -list -raw
	1522639699      "curling"        start   
	1522640897      "curling"        end     19:58
	#######################################################      Mon Apr 2, 2018
	1522645200      "development"    start   
	1522657800      "development"    end     3:30:00
	1522680826      "testing"        start   
	1522686225      "testing"        end     1:29:59
	#######################################################      Tue Apr 3, 2018
	1522729116      "development"    start   
	1522732367      "development"    end     0:54:11
	#######################################################      Thu Apr 5, 2018
	1522945292      "development"   start

	$ chronosquirrel -list -rare
	Sun Apr  1 23:28:19 2018        "curling"        start
	Sun Apr  1 23:48:17 2018        "curling"        end     0:19:58

	Mon Apr  2 01:00:00 2018        "development"    start
	Mon Apr  2 04:30:00 2018        "development"    end     3:30:00
	Mon Apr  2 10:53:46 2018        "testing"        start
	Mon Apr  2 12:23:45 2018        "testing"        end     1:29:59

	Tue Apr  3 00:18:36 2018        "development"    start
	Tue Apr  3 01:12:47 2018        "development"    end     0:54:11

	Thu Apr  5 12:21:32 2018        "development"    start

	$ chronosquirrel -list -cooked
	Sun Apr  1 23:28:19 2018  "curling"	Sun Apr  1 23:48:17 2018        0:19
	Mon Apr  2 01:00:00 2018  "development"	Mon Apr  2 04:30:00 2018        3:30
	Mon Apr  2 10:53:46 2018  "testing"     Mon Apr  2 12:23:45 2018        1:29
	Tue Apr  3 00:18:36 2018  "development" Tue Apr  3 01:12:47 2018        0:54
	Thu Apr  5 12:21:32 2018  "development"                                 2:20

	$ # when executed on 4/2/18...
	$ chronosquirrel -list -cooked -day
	Mon Apr  2 01:00:00 2018  "development"	Mon Apr  2 04:30:00 2018        3:30
	Mon Apr  2 10:53:46 2018  "testing"     Mon Apr  2 12:23:45 2018        1:29



3. OUTPUT MODES

Output from chronosquirrel is given in one of three modes: cooked, rare, and raw. cooked mode is the most processed; raw mode is the least processed. The particular characteristics of each mode are as follows:



4. CONFIGURATION FILE

The chronosquirrel configuration file is in ~/.chronosquirrelrc. The most important purpose of this file is to define all tasks that will be tracked by chronosquirrel. The definitions in the configuration file supersede the built-in default values. They are superseded by related command-line options.

The following things are saved in the configuration file:

Fields within each line may be separated by spaces or tabs.

Any line starting with a pound sign ('#') is a comment line and is ignored.

Spaces may precede any comment or other type of line, and will be ignored.

Blank lines are ignored.

4.1. Task Definitions

Task definitions look like this:

	task "taskname"	billable-flag	ordering-number
The fields are described in the
General Use section above. The fields have these restrictions:

4.2. Task Name Aliases

Task name aliases provide alternate ways to refer to a particular task. These may be abbreviations or alternate names. The aliases are not used in chronosquirrel output; they are only intended for convenience use on the command line. Alias definitions look like this:

	alias "taskname" "alias 1", "alias 2", ..., "alias N"
The fields have these restrictions:

4.3. Kronlog File

This file stores the kron entries used to track task times. The kronlog path definition looks like this:

	log "/path/to/kronlog"
The field has these restrictions:

4.4. Seconds-Display Flag

This flag defines how seconds are displayed by chronosquirrel. The def value uses the script's default behavior. The off value forces chronosquirrel to not give seconds. The on value forces chronosquirrel to always give seconds.

The seconds variable definition looks like this:

	seconds def
	seconds off
	seconds on
The fields have these restrictions:

4.5. US-Location Flag

This flag defines whether or not the local instance of chronosquirrel is being run in the US or outside of the US. The only effect this has is to determine the interpretation of dates entered on the command line.

If this flag has a true value, the dates are interpreted as MM/DD. If it has a false value, then dates are interpreted as DD/MM.

True values can be given as true, yes, or 1.

False values can be given as false, no, or 0.

If the .chronosquirrelrc file does not has a us-location entry, the default value is true.

4.6. Example .chronosquirrelrc

	#
	# This is a simple .chronosquirrelrc file.  It is using the
	# tasks defined in the "Defining Tasks" section of
	# the chronosquirrel documentation.
	#

	#
	# Task definitions.
	#
	task  "development"	billable	1

	task  "curling" nonbillable		200
	task  "breaks" nonbillable		88

	task  "testing"              billable	30

	#
	# Alias definitions.
	#
	alias  "testing"		"tst"
	alias  "development"	"dev", "coding"
	alias  "breaks"         "lunch", "coffee", "tea"

	#
	# We'll put the kronlog in a nonstandard place.
	# The tilde is expanded appropriately.
	#
	log	"~/kronlogs/2018-krons"


	#
	# Don't show any seconds in the displayed timings.
	#
	seconds	off

	#
	# We want non-US versions of dates.
	#
	us-location	no


5. MANAGING KRONLOGS

chronosquirrel usually does a good job of taking care of its data files. However, there are situations where the kronlog must be modified. For examples, adding an entry after its actual occurrence, fixing a time that was recorded, deleting an entry, and rolling a kronlog to a new file. These are most often due to such things as forgetting to start the timer, forgetting to stop the timer, or needing to start/stop a timer when the computer is unavailable, or time change to a new year. Such kronlog edits can be performed manually, but this is prone to error and it can be difficult to select the proper epoch time.

chronosquirrel provides several options to facilitate such extra-chronicular adjustments.

5.1. Inserting New Krons

The -insertkron option provides a means to easily insert a new kron block into the kronlog. This option creates the new kron block, inserts it into the proper place in the kronlog, and ensures that it won't interfere with the existing entries. It also will insert multiple kron blocks into if the time spans midnight. All these are handled automatically by chronosquirrel.

This option must be accompanied by several arguments. The first three arguments are always the same: a task name, a starting date, and a starting time or time range. The remaining arguments can be an entry duration or the date and time of the entry's end. The presence or absence of some of the later arguments will depend on the arguments that come before. Formats and caveats will be given below.

The task name may be an actual task name or a task alias.

Dates are always in either a "MM/DD/YY" or a "MM/DD" format. Years are assumed to be in the range 2000 to 2099. Leading zeroes may be given or left off. So, February 14, 2021 would be specified as either "2/14/21" or "02/14/21". If the year is not included, the current year is assumed.

Times are always in either an "HH:MM:SS" or a "HH:MM" format. Hours are given in the 24-hour format. Leading zeroes may be given or left off. So, 25 minutes and 42 seconds after 8AM would be given as either "8:25:42" or "08:25:42". If the seconds are not included, the seconds are set to "00".

A time range is two times (as defined above) that are separated by a dash. The two times are assumed to be on the same day. The first time must be earlier than the second time.

The various forms of the -insertkron option are:

There are several restrictions on using the -insertkron option:

5.2. Editting an Existing Kron

The -changekron option provides a method to easily modify an existing kron block in the kronlog. This option finds the selected kron block, makes the appropriate change, ensures that it won't interfere with the existing entries, and then saves the modified log file.

This option must be accompanied by two groups of arguments. The first group selects the kron to be changed. The second group contains the new values for the selected kron.

Generally speaking, the -changekron option will look like this:

    chronosquirrel -changekron  

The selection arguments are always the same: a task name, a date, and a time. The date and time must fall within an existing kron; it can be the starting date and time, the ending date and time, or any time between.

The new-value arguments are the same as the arguments used for the -insertkron option. These arguments are described fully in the Inserting New Krons section. In short, though, these arguments are a taskname, the start date/time, and either a duration or an end date/time. The ordering of these arguments is important, and matches the ordering used by -insertkron.

Putting it all together, the -changekron option will look like one of these templates:

    chronosquirrel -changekron task date time newtask newdate1 newtime1 elapsed
    chronosquirrel -changekron task date time newtask newdate1 newtime1 newdate2 newtime2

Some of the option arguments at the end of these templates may be omitted, depending on the actual operation desired.

The special value "=" can be used as a new-value argument to indicate that one or more of the selected kron's values should stay the same. At least one of the new-value arguments must be an actual value, but all of the others can be the special "=" value. The examples below should make this clear.

Data used in these examples are taken from the lines below.

    Mon May 28 09:00:00 2018  "development"  Mon May 28 11:00:00 2018 2:00:00
    Mon May 28 11:06:40 2018  "testing"      Mon May 28 12:21:40 2018 1:15:00
    Mon May 28 19:26:40 2018  "development"  Mon May 28 20:11:40 2018 0:45:00

Examples of the -changekron option follow:

As with some other options, -changekron backs up the kronlog file prior to making any changes. It might be helpful to experiment with this option, and recover from the back-up if something unexpected happens.

5.3. Deleting an Existing Kron

The -deletekron option allows for deletion of an existing kron block from the B. This option searches the kron log to find a kron block that contains a time specified by the user. Once found, the entries that comprise that block are deleted from the kronlog.

This option must be accompanied by three arguments. The three arguments are always the same: a task name, a date, and a time.

The task name may be an actual task name or a task alias. The task name must match the name given in the kron entries. Strictly speaking, this requirement isn't necessary, but it might help ensure that the correct kron block will be deleted.

The user-specified date/time matches a kron block if it is matches or is between the times given on the block's start and end lines. An open kron block can also be deleted. In this case only the start entry is found and deleted.

Dates are always in either a "MM/DD/YY" or a "MM/DD" format. Years are assumed to be in the range 2000 to 2099. Leading zeroes may be given or left off. So, February 14, 2021 would be specified as either "2/14/21" or "02/14/21". If the year is not included, the current year is assumed.

Times are always in either an "HH:MM:SS" or a "HH:MM" format. Hours are given in the 24-hour format. Leading zeroes may be given or left off. So, 25 minutes and 42 seconds after 8AM would be given as either "8:25:42" or "08:25:42". If the seconds are not included, the seconds are set to "00".

Data used in these examples are taken from the lines below.

    1527519600  "dev"   start
    1527525000  "dev"   end     1:30:00

    Mon May 28 11:00:00 2018  "dev"       Mon May 28 12:30:00 2018    1:30:00
The form of the -deletekron option is:

5.4. Manual Editting of an Existing Kron

This is not recommended, strongly. However, this section contains a few hints as to how to do this.

5.5. Rolling Kronlog Files

Extensive use of chronosquirrel will result in a potentially large kronlog file. Entries will be added to the end of the file without regard for the file size. In order to keep kronlog files to a manageable size, the kronlog file may be rolled using the -roll option. Rolling a kronlog file will move all the entries before a specified roll point into a roll file, and leave all the entries from the roll point onwards in the original kronlog file.

The roll point is the last crossing point between the relevant method items. A day roll will leave the final day's entries in the kronlog file; all the earlier days' entries will be moved to a roll file. A month roll will leave the final month's entries in the kronlog file, while all the earlier months' entries will be moved to a roll file. The two date-specific roll points (MM/DD and MM/DD/YY) split the kronlog file at midnight of the specified date, regardless of where the date falls in the year.

To roll the kronlog file, chronosquirrel must be invoked with the desired method argument. This argument indicates the roll point at which the kronlog file will be split. The method selects the relevant point closest to the end of the file. The following are the valid methods:

For example, running chronosquirrel -roll month will find the last change from one month to another in the default kronlog file, and move all the preceding kron entries into a roll file. The table below shows an original kronlog file, followed by the post-roll kronlog file (on a month roll) and the roll file.

  Original kronlog File
Wed Feb 21 10:00:00 2018  "curling"     Wed Feb 21 12:00:00 2018        2:00
Thu Mar 29 10:30:00 2018  "testing"     Thu Mar 29 18:30:45 2018        8:00
Fri Mar 30 09:45:00 2018  "development" Fri Mar 30 17:15:17 2018        7:30
Sun Apr  1 23:28:19 2018  "curling"	Sun Apr  1 23:48:17 2018        0:19
Mon Apr  2 01:00:00 2018  "development"	Mon Apr  2 04:30:00 2018        3:30
  Post-Roll kronlog File — month Method
Sun Apr  1 23:28:19 2018  "curling"	Sun Apr  1 23:48:17 2018        0:19
Mon Apr  2 01:00:00 2018  "development"	Mon Apr  2 04:30:00 2018        3:30
  Roll File
Wed Feb 21 10:00:00 2018  "curling"     Wed Feb 21 12:00:00 2018        2:00
Thu Mar 29 10:30:00 2018  "testing"     Thu Mar 29 18:30:45 2018        8:00
Fri Mar 30 09:45:00 2018  "development" Fri Mar 30 17:15:17 2018        7:30

The roll file is given a name that is based on the kronlog file's name. A suffix is add to the file's name that consists of "-YYMMDD.roll", where "YYMMDD" is the year, month, and day of the day of the roll's roll point. If multiple rolls are done for that roll point, then an index number will be included. In this case, the suffix template is "-YYMMDD-NN.roll".

The original kronlog file is backed up prior to the roll. The backup file follows the naming scheme described in the Health Files section.

5.6. Annotating Kronlog Files

A user may want to add explanatory comments for particular times to a kronlog file. Of course, this can be done manually using a text editor; however, chronosquirrel also provides an option to make this easy. The -annotate option allows the user to add comments to the kronlog file. A timestamp must be given, which determines where exactly the comment will be placed. Several arguments must be included with the option: the date, the time, and the comment itself. There are several optional arguments that may also be specified.

Even though the annotation command includes a timestamp, the timestamp is not included in the annotation. Once placed, the annotation's timestamp does not carry forward in the file.

There are two types of timestamps that may be given:

  1. kron-based annotations
    chronosquirrel keeps its time records in kron entries. Each complete entry consists of two lines; one indicates the start of the record and the second indicates the end of that record. For kron-based annotations, the timestamp may indicate any time within a particular kron. The timestamp may consist of a record's start time, end time, or any time between them. The annotation will be placed immediately before the kron entry's "start" line. This is the default annotation type.

  2. exact-time annotations
    More fine-grained control over the placement of an annotation comes with using exact-time annotations. The proper location in the kronlog will be found by comparing the annotation's timestamp to the timestamp of each non-comment line in the kronlog file. If the annotation's timestamp exactly matches the timestamp of an kron entry, then the annotation will be placed before the entry. Otherwise, it will be placed in the proper place in relation to the timestamps of the file's kron entries. This annotation type is specified with an annotation command argument.

Examples of each type are given below.

5.6.1. Format of Annotation Commands

The general format of annotation is:

        chronosquirrel -annotate [options] date time message
The annotation fields of command are:

5.6.2. Examples of Annotation Commands

Examining some examples of annotation commands may help in understanding how chronosquirrel's annotations work. All of the examples will start with this file, and the command below will show the annotation results.

	1543071600	"development"	start
	1543075200	"development"	end	1:00:00
	1543078800	"testing"	start
	1543082400	"testing"	end	1:00:00

  1. Basic kron-based Annotation
    This command adds an annotation at the beginning of the development task.
        $ chronosquirrel -annotate 11/24 10:30 Started working on gossamer.
    
    Results in:
    	# Started working on gossamer.
    	1543071600	"development"	start
    	1543075200	"development"	end	1:00:00
    	1543078800	"testing"	start
    	1543082400	"testing"	end	1:00:00
    

  2. Basic Exact-Time Annotation
    This command adds an annotation in the middle of the development task.
        $ chronosquirrel -annotate x 11/24 10:30 Started working on gossamer.
    
    Results in:
    	1543071600	"development"	start
    	# Started working on gossamer.
    	1543075200	"development"	end	1:00:00
    	1543078800	"testing"	start
    	1543082400	"testing"	end	1:00:00
    

  3. kron-based Annotation with Timestamp
    This command adds an annotation at the beginning of the development task. An annotation timestamp is included.
        $ chronosquirrel -annotate t 11/24 10:30 Started working on gossamer.
    
    Results in:
    	# 11/24/18 10:30:00  Started working on gossamer.
    	1543071600	"development"	start
    	1543075200	"development"	end	1:00:00
    	1543078800	"testing"	start
    	1543082400	"testing"	end	1:00:00
    

  4. Exact-Time Annotation with Timestamp
    This command adds an annotation in the middle of the development task. An annotation timestamp is included.
        $ chronosquirrel  -annotate xt 11/24 10:30 Started working on gossamer.
    
    Results in:
    	1543071600	"development"	start
    	# 11/24/18 10:30:00  Started working on gossamer.
    	1543075200	"development"	end	1:00:00
    	1543078800	"testing"	start
    	1543082400	"testing"	end	1:00:00
    

  5. kron-based Annotation with a Separator
    This command adds an annotation at the beginning of the development task. A separator is included before the annotation.
        $ chronosquirrel -annotate s 11/24 10:30 Started working on gossamer.
    
    Results in:
    
    	#-------------------------------------------------------------------------------
    	# Started working on gossamer.
    	1543071600	"development"	start
    	1543075200	"development"	end	1:00:00
    	1543078800	"testing"	start
    	1543082400	"testing"	end	1:00:00
    

  6. Exact-Time Annotation with "Pretty Printing"
    This command adds an annotation in the middle of the development task. The annotation has some additional comments added for extra spacing.
        $ chronosquirrel  -annotate px 11/24 10:30 Started working on gossamer.
    
    Results in:
    	1543071600	"development"	start
    	#
    	# Started working on gossamer.
    	#
    	1543075200	"development"	end	1:00:00
    	1543078800	"testing"	start
    	1543082400	"testing"	end	1:00:00
    

  7. Annotation with All the Options
    This command adds an annotation in the middle of the development task. An annotation timestamp, a separator, and prettifying comments are included.
        $ chronosquirrel  -annotate sxtp 11/24 10:30 Started working on gossamer.
    
    Results in:
    	#-------------------------------------------------------------------------------
    	#
    	# 11/24/18 9:30:00  Started working on gossamer.
    	#
    	1543071600	"development"	start
    	1543075200	"development"	end	1:00:00
    	1543078800	"testing"	start
    	1543082400	"testing"	end	1:00:00
    

5.6.3. Details of Annotation Placings

It may not be clear just how the kron-based annotations and the exact-time annotations differ. This section will present a set of annotation commands and the resulting files for both types of annotation.

5.6.3.1. Original kronlog File

The kronlog file stores timestamps as epoch times, but epoch times are not the easiest things for humans to parse. The examples kronlog files in this section will be shown in the original, epoch-time form, as well as in a translated form. The translation will show the actual date and time instead of the epoch time. This should make it easier to relate the log data to the commands executed to create the annotations.

Translated kronlog File   Original kronlog File
#
# Translated time log used for testing chronosquirrel.
#
11/24/18 08:00:00	"testing"	start
11/24/18 09:00:00	"testing"	end	1:00:00

11/24/18 10:00:00	"development"	start
11/24/18 11:00:00	"development"	end	1:00:00

11/24/18 12:00:00	"testing"	start
11/24/18 13:00:00	"testing"	end	1:00:00

11/24/18 14:00:00	"development"	start
11/24/18 15:00:00	"development"	end	1:00:00

11/24/18 16:00:00	"testing"	start
11/24/18 17:00:00	"testing"	end	1:00:00

11/24/18 18:00:00	"curling"	start
11/24/18 19:00:00	"curling"	end	1:00:00
 
#
# Original time log used for testing chronosquirrel.
#
1543064400	"testing"	start
1543068000	"testing"	end	1:00:00
1543071600	"development"	start
1543075200	"development"	end	1:00:00
1543078800	"testing"	start
1543082400	"testing"	end	1:00:00
1543086000	"development"	start
1543089600	"development"	end	1:00:00
1543093200	"testing"	start
1543096800	"testing"	end	1:00:00
1543100400	"curling"	start
1543104000	"curling"	end	1:00:00

5.6.3.2. kron-based kronlog File

To create the annotated kron-based kronlog file, the following ordered sequence of commands were executed:
        chronosquirrel -annotate 11/24 t 7:00 msg 1

        chronosquirrel -annotate 11/24 t 8:00 msg 2

        chronosquirrel -annotate 11/24 t 8:30 msg 3

        chronosquirrel -annotate 11/24 t 9:00 msg 4

        chronosquirrel -annotate 11/24 t 9:59 msg 5

        chronosquirrel -annotate 11/24 t 10:00 msg 6

        chronosquirrel -annotate 11/24 t 10:01 msg 7

        chronosquirrel -annotate 11/24 t 19:00 msg 8

        chronosquirrel -annotate 11/24 t 20:00 msg 9

The t option was used in order to include the timestamp in the annotation message.

The annotated kronlog file (in original and translated forms) are:

Translated kron-based kronlog File   Original kron-based kronlog File
#
#		kron-based annotations
#
# 11/24/18 7:00:00  msg 1
# 11/24/18 8:00:00  msg 2
# 11/24/18 8:30:00  msg 3
# 11/24/18 9:00:00  msg 4
11/24/18 08:00:00	"testing"	start
11/24/18 09:00:00	"testing"	end	1:00:00
# 11/24/18 9:59:00  msg 5
# 11/24/18 10:00:00  msg 6
# 11/24/18 10:01:00  msg 7
11/24/18 10:00:00	"development"	start
11/24/18 11:00:00	"development"	end	1:00:00
11/24/18 12:00:00	"testing"	start
11/24/18 13:00:00	"testing"	end	1:00:00
11/24/18 14:00:00	"development"	start
11/24/18 15:00:00	"development"	end	1:00:00
11/24/18 16:00:00	"testing"	start
11/24/18 17:00:00	"testing"	end	1:00:00
# 11/24/18 19:00:00  msg 8
11/24/18 18:00:00	"curling"	start
11/24/18 19:00:00	"curling"	end	1:00:00
# 11/24/18 20:00:00  msg 9
 
#
#		kron-based annotations
#
# 11/24/18 7:00:00  msg 1
# 11/24/18 8:00:00  msg 2
# 11/24/18 8:30:00  msg 3
# 11/24/18 9:00:00  msg 4
1543064400	"testing"	start
1543068000	"testing"	end	1:00:00
# 11/24/18 9:59:00  msg 5
# 11/24/18 10:00:00  msg 6
# 11/24/18 10:01:00  msg 7
1543071600	"development"	start
1543075200	"development"	end	1:00:00
1543078800	"testing"	start
1543082400	"testing"	end	1:00:00
1543086000	"development"	start
1543089600	"development"	end	1:00:00
1543093200	"testing"	start
1543096800	"testing"	end	1:00:00
# 11/24/18 19:00:00  msg 8
1543100400	"curling"	start
1543104000	"curling"	end	1:00:00
# 11/24/18 20:00:00  msg 9

5.6.3.3. Exact-Time kronlog File

Compare those results with the following commands and results, which use the exact-time annotation method.

As above, the following sequence of commands were executed in order:

        chronosquirrel -annotate 11/24 xt 7:00 msg 1

        chronosquirrel -annotate 11/24 xt 8:00 msg 2

        chronosquirrel -annotate 11/24 xt 8:30 msg 3

        chronosquirrel -annotate 11/24 xt 9:00 msg 4

        chronosquirrel -annotate 11/24 xt 9:59 msg 5

        chronosquirrel -annotate 11/24 xt 10:00 msg 6

        chronosquirrel -annotate 11/24 xt 10:01 msg 7

        chronosquirrel -annotate 11/24 xt 19:00 msg 8

        chronosquirrel -annotate 11/24 xt 20:00 msg 9

In addition to the t option being used for the timestamp, the x option indicated the use of exact-time annotations.

The annotated kronlog file (in original and translated forms) are:

Translated Exact-Time kronlog File   Original Exact-Time kronlog File
#
#		exact-time annotations
#
# 11/24/18 7:00:00  msg 1
# 11/24/18 8:00:00  msg 2
11/24/18 08:00:00	"testing"	start
# 11/24/18 8:30:00  msg 3
# 11/24/18 9:00:00  msg 4
11/24/18 09:00:00	"testing"	end	1:00:00
# 11/24/18 9:59:00  msg 5
# 11/24/18 10:00:00  msg 6
11/24/18 10:00:00	"development"	start
# 11/24/18 10:01:00  msg 7
11/24/18 11:00:00	"development"	end	1:00:00
11/24/18 12:00:00	"testing"	start
11/24/18 13:00:00	"testing"	end	1:00:00
11/24/18 14:00:00	"development"	start
11/24/18 15:00:00	"development"	end	1:00:00
11/24/18 16:00:00	"testing"	start
11/24/18 17:00:00	"testing"	end	1:00:00
11/24/18 18:00:00	"curling"	start
# 11/24/18 19:00:00  msg 8
11/24/18 19:00:00	"curling"	end	1:00:00
# 11/24/18 20:00:00  msg 9
 
#
#		exact-time annotations
#
# 11/24/18 7:00:00  msg 1
# 11/24/18 8:00:00  msg 2
1543064400	"testing"	start
# 11/24/18 8:30:00  msg 3
# 11/24/18 9:00:00  msg 4
1543068000	"testing"	end	1:00:00
# 11/24/18 9:59:00  msg 5
# 11/24/18 10:00:00  msg 6
1543071600	"development"	start
# 11/24/18 10:01:00  msg 7
1543075200	"development"	end	1:00:00
1543078800	"testing"	start
1543082400	"testing"	end	1:00:00
1543086000	"development"	start
1543089600	"development"	end	1:00:00
1543093200	"testing"	start
1543096800	"testing"	end	1:00:00
1543100400	"curling"	start
# 11/24/18 19:00:00  msg 8
1543104000	"curling"	end	1:00:00
# 11/24/18 20:00:00  msg 9



6. CHRONOSQUIRREL HEALTH

chronosquirrel uses two files, each of which must be checked to ensure it has not been corrupted. The -health option will validate these files. The health checks will fix what they can automatically. If any problems require user intervention, the problems will be reported and the program will stop.

After the tests have run without finding errors, a modified kronlog may be written to the log file. If the -fixit option was given, then this will be done automatically; if -fixit wasn't given, the user will be prompted for permission to save the modifications.

To keep a kronlog file to a manageable size, the file should be rolled periodically. Log rolling is discussed in the Rolling Kronlog Files section.

When a modified kronlog is saved by the health procedures, the original kronlog is backed up Just In Case. See the Health Files section for details on where the backups are stored.

6.1. Configuration File Validation

chronosquirrel checks the configuration file for validity every time the file is read. This happens on almost every execution, including when the -health option is given.

The following potential problems are checked:

6.2. Kronlog File Validation

chronosquirrel checks the kronlog file for validity whenever the script is given the -health option.

The kronlog tests are divided into three groups. The first group tests for problems that cannot be fixed automatically. If any of these tests fail, the check-up will stop after all the group 1 tests have run.

The group 2 tests will be run if all of the group 1 tests pass. The group 2 tests will attempt to fix errors they find.

The group 3 test ensures that all time values are monotonically ascending. This is checked in group 1, but group 2 can add entries to the kronlog, so the check is required again.

The following potential problems are checked by group 1 tests:

The following potential problems are checked by group 2 tests:

6.3. Health Files

~/.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.



7. OPTIONS

chronosquirrel takes the following options:



8. FILES

~/.chronosquirrelrc - Configuration file for chronosquirrel.

~/.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.



9. CREDITS AND LICENSE

chronosquirrel was written by Wayne Morrison. He may be reached at wayne@waynemorrison.com.

9.1. Document Version

The version of this User's Guide follows the version numbers of chronosquirrel itself. This document is updated whenever chronosquirrel is updated, so this versioning system is the logical one to follow.

Version Updates Date
1         Basic Functionality  
1.0 Initial revision. 180329
1.1 Added selection of day or week to display.
Turned off automatic display of unused tasks.
Added periodic automatic display of status.
Added us-location in config file.
180411
1.2 Added selection of date or date range for -listkrons.
Centralized stripping of comments and blanks from kronlog.
180413
1.3 Added health checks for the config and kronlog files.
Modified stop lines in the kronlog to use HH:MM:SS
for time-diff field, rather than difference in epoch times.
180422
1.4 Added active/inactive status for tasks. 180424
2         Editting capabilities.  
2.0 Added -insertkron. 180522
2.1 Added -deletekron.
Added licensing info.
180531
2.2 Added -changekron. 180705
2.3 Fixed bug in status display. 180718
2.4 Check for krons crossing midnight.
Prevent krons from starting after one with a later date.
180825
2.5 Moved most of the pod into a separate User's Guide. 180829
2.6 Added -today recognition to -list.
Added -weekly recognition to -list.
Added -day as a synonym for -today and -daily.
180909
2.6.1 Moved all kronlog appends into new appendkron(). 180927
2.7 Added -roll for log rolling. 180927
2.8 Added -annotate for kronlog annotations. 181126

9.2. License Information

Copyright © 2018 Wayne Morrison

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

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.