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.
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.
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:
Examples:
Examples:
Example:
Example:
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:
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.
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:
The following things are saved in the configuration file:
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.
The seconds variable definition looks like this:
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.
chronosquirrel provides several options to facilitate such
extra-chronicular adjustments.
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:
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:
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:
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.
Examples of the -changekron option follow:
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.
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.
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:
Examples of each type are given below.
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.
The following potential problems are checked:
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:
~/.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.
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.
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.
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.
The full definition of selection-criteria is:
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.
The output mode determines how the billable column is shown:
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",
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.
~/.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.
At some point, chronosquirrel might be modified to allow the user to
specify the starting day of the week, but this is a low priority. It may
also be modified to allow the user to choose to use the ISO week, but that
is even lower in priority.
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.
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.
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.
Example tasks:
The only reserved taskname is "Off Clock".
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.
$ 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.
$ 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.
$ 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.
$ 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.
$ 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".
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.
$ 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.
Fields within each line may be separated by spaces or tabs.
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.
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.
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.
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.
chronosquirrel -insertkron dev 10/14 11:00 10/14 17:30
chronosquirrel -insertkron party 12/31/18 22:00 1/1/18 2:30
chronosquirrel -insertkron party 12/31 22:00 1/1/18 2:30
chronosquirrel -insertkron dev 10/14 11:00-17:30
chronosquirrel -insertkron dev 10/14/18 11:00-17:30
chronosquirrel -insertkron dev 10/14 11:00 6:30
chronosquirrel -insertkron dev 10/14/18 11:00 6:30
chronosquirrel -insertkron party 12/31/18 22:00 4:30
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.
chronosquirrel -changekron
chronosquirrel -changekron task date time newtask newdate1 newtime1 elapsed
chronosquirrel -changekron task date time newtask newdate1 newtime1 newdate2 newtime2
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
chronosquirrel -changekron testing 5/28 11:06:40 development
chronosquirrel -changekron testing 5/28 12:21:40 development
chronosquirrel -changekron testing 5/28 12:21 development
chronosquirrel -changekron testing 5/28 12:00 development
will each change the second entry to:
Mon May 28 11:06:40 2018 "development" Mon May 28 12:21:40 2018 1:15:00
chronosquirrel -changekron testing 5/28 11:06:40 development 5/28 11:00
chronosquirrel -changekron testing 5/28 12:21:40 development 5/28 11:00
chronosquirrel -changekron testing 5/28 12:00 development 5/28 11:00
change the second entry to:
Mon May 28 11:00:00 2018 "development" Mon May 28 12:15:00 2018 1:15:00
chronosquirrel -changekron testing 5/28 11:06:40 development 5/28 11:00 1:30
chronosquirrel -changekron testing 5/28 12:21:40 development 5/28 11:00 1:30
chronosquirrel -changekron testing 5/28 12:00 development 5/28 11:00 1:30
change the second entry to:
Mon May 28 11:00:00 2018 "development" Mon May 28 12:30:00 2018 1:30:00
chronosquirrel -changekron testing 5/28 11:06:40 development 5/28 11:00 12:30
chronosquirrel -changekron testing 5/28 12:21:40 development 5/28 11:00 12:30
chronosquirrel -changekron testing 5/28 12:00 development 5/28 11:00 12:30
change the second entry to:
Mon May 28 11:00:00 2018 "development" Mon May 28 12:30:00 2018 1:30:00
chronosquirrel -changekron testing 5/28 11:06:40 = = 11:00 = 13:30
chronosquirrel -changekron testing 5/28 12:21:40 = = 11:00 = 13:30
chronosquirrel -changekron testing 5/28 12:00 = = 11:00 = 13:30
change the second entry to:
Mon May 28 11:00:00 2018 "testing" Mon May 28 13:30:00 2018 2:30:00
chronosquirrel -changekron testing 5/28 11:06:40 = = = = 13:30
chronosquirrel -changekron testing 5/28 12:21:40 = = = = 13:30
chronosquirrel -changekron testing 5/28 12:00 = = = = 13:30
change the second entry to:
Mon May 28 11:06:40 2018 "testing" Mon May 28 13:30:00 2018 2:23:20
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
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:
chronosquirrel -deletekron dev 5/28 11:00
chronosquirrel -deletekron dev 5/28/18 11:30
chronosquirrel -deletekron dev 5/28 12:30
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
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.
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.
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.
1543071600 "development" start
1543075200 "development" end 1:00:00
1543078800 "testing" start
1543082400 "testing" end 1:00:00
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
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
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
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
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
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
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
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
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
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.
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.
6.2. Kronlog File Validation
chronosquirrel checks the kronlog file for validity whenever the
script is given the -health option.
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.
7. OPTIONS
chronosquirrel takes the following options:
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.
8. FILES
~/.chronosquirrelrc - Configuration file for chronosquirrel.
9. IMPORTANT CAVEATS
There are several important things that chronosquirrel users must be
aware of.
10. CREDITS AND LICENSE
chronosquirrel was written by Wayne Morrison. He may be reached
at wayne@waynemorrison.com.
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
10.2. License Information
Copyright © 2018 Wayne Morrison