tracker is a tool to help track daily personal metrics. each metric is a count of something per day. the point is to measure behaviors that you are trying to increase (like excercise) or decrease (like watching buffy the vampire slayer) so that you can see if you are making progress toward that goal.
You cannot measure something without affecting it. don't argue; that's science. personal decisions are probably outside the scope of quantum mechanics, but lets not get caught up in details.
tracker keeps a repository of occurrences for each metric from which it can generate a variety of reports. tracker is like a spreadsheet with a command line interface.
- gnuplot (for rendering graphs)
> neko /path/to/tracker.n
on linux, setting an alias can save a few keystrokes.
to use the
graph command you must have gnuplot installed and on your
system path. be sure to install the full gnuplot package, which
includes the cairo libraries.
modifying the repo
tracker has a command line interface similar to git's. to begin using it, you must initialize a repo. by default tracker will create a repo called '.tracker.db' in your home directory. initialize it with:
> tracker init creating repository: /home/ian/.tracker.db
if that didn't crash, I guess your installation is ok.
now lets put something in the repo:
> tracker set pushups =50 set pushups to 50 for 2012-02-26
that created a metric call 'pushups' and stored '50' in it for today
(2012-02-26). the space between the
=50 is required.
values can have decimal parts and can be negative.
maybe you just did a few more. lets update the repo:
> tracker set pushups +5 set pushups to 55 for 2012-02-26
that increased the existing value by 5. a
-5 will decrease a
metric's value. if you don't specify a date,
set uses the current
day. you can specify a date with the
> tracker set =40 pushups -d 2012-02-20 set pushups to 40 for 2012-02-20
that set '40' to the 'pushups' metric for feb 20th. the order of
arguments doesn't matter except that the first argument must be the
command. dates can be specified in either
YYYY-MM-DD format, or as
today-1 is the same as
> tracker set pullups =10 -d yesterday set pullups to 10 for 2012-02-25
that created the 'pullups' metric and set its value to '10' for feb 25th (yesterday).
tracker also accepts date ranges. the following will set all of the days from feb 10th until the 15th (inclusive) to '4' for 'watchedtv':
> tracker set watchedtv =4 -d 2012-02-10..2012-02-15 set watchedtv to 4 for 2012-02-10 set watchedtv to 4 for 2012-02-11 set watchedtv to 4 for 2012-02-12 set watchedtv to 4 for 2012-02-13 set watchedtv to 4 for 2012-02-14 set watchedtv to 4 for 2012-02-15
note: tracker doesn't care about units. the '4' could mean 4 shows, or could mean 4 hours.
lets say you didn't actually watch tv on the 12th. you can delete that entry with:
> tracker rm watchedtv -d 2012-02-12 removed watchedtv for 2012-02-12
if you left the date off, tracker would have tried to delete a
'watchedtv' entry for today (but there isn't one). date ranges for
modifier commands (
rm) default to
that's it for the commands that modify the repo. now lets look at some reporting.
list command lists all metrics stored in the repo and gives
their date ranges.
> tracker list metric count first last days pushups 2 2012-02-20 to 2012-02-26 7 pullups 1 2012-02-25 to 2012-02-25 1 watchedtv 5 2012-02-10 to 2012-02-15 6
streaks command lists runs of consecutive days with or without
> tracker streaks watchedtv duration: 17 days from 2012-02-10 to 2012-02-26 on 2 days from 2012-02-10 off 1 day from 2012-02-12 on 3 days from 2012-02-13 off 11 days from 2012-02-16
since the date range isn't specified, tracker uses the full date range of the data. the full date range for report commands is from the first occurrence to the current day. all reports begin by specifying the duration of the date range examined.
this is the calendar view of the same data. here you can easily see
the runs of on and off days that were listed by the
> tracker cal watchedtv duration: 29 days from 2012-02-01 to 2012-02-29 Feb 2012 Su Mo Tu We Th Fr Sa . . . . . . . . . 4 4 . 4 4 4 . . . . . . . . . . . _ _ _
note: the underscores represent days in the future.
this is the calendar for both the 'pullups' and 'pushups' metrics. listing multiple metrics will return occurrences of either. values for the same day will be summed.
> tracker cal pullups pushups duration: 29 days from 2012-02-01 to 2012-02-29 Feb 2012 Su Mo Tu We Th Fr Sa . . . . . . . . . . . . . . . . . . . 40 . . . . 10 55 _ _ _
the following is a log of all 'watchedtv' occurrences. by default, logs group occurrences by day, but they can also be grouped in larger intervals.
> tracker log watchedtv duration: 17 days from 2012-02-10 to 2012-02-26 2012-02-10: 4 2012-02-11: 4 2012-02-13: 4 2012-02-14: 4 2012-02-15: 4
note: logs, like all reports, can be constrained using date ranges.
this is a log where each entry lists the totals for that week.
> tracker log watchedtv -by-week duration: 17 days from 2012-02-10 to 2012-02-26 2012-02-05: 8 2012-02-12: 12
so, on the week of the 12th, you spent 12 hours watching tv. you
should pare that back. in addition to
-by-week, tracker provides
-by-full, which combines all
data into a single entry.
note: day logs omit gaps in data, but the other date groupings show gaps as zero entries.
in the last example the values reported were sums of the metric values. that's the default, but tracker can also provide counts of occurrences:
> tracker log watchedtv -by-week -count duration: 17 days from 2012-02-10 to 2012-02-26 2012-02-05: 2 2012-02-12: 3
that last line says that you watched tv on three days of the week of feb 12th.
you can also get averages of values. here, tracker totals the values (20 in this example) then divides by the number of weeks in the interval (2), resulting in 5.
> tracker log watchedtv -by-month -per-week duration: 17 days from 2012-02-10 to 2012-02-26 2012-02: 5
that says you spent 5 hours per week watching tv in feb.
you can also get percentages of occurrences. here, tracker counts the occurrences, then divides by the number of days in the interval (7 again) then converts to a percent.
> tracker log watchedtv -by-week -percent duration: 17 days from 2012-02-10 to 2012-02-26 2012-02-05: 29 2012-02-12: 43
that says that you watched tv on 43% of the days of the week of feb 12th.
the command below shows the highest and lowest values for each interval.
> tracker records pushups pullups duration: 7 days from 2012-02-20 to 2012-02-26 highest year: 2012 (105) lowest year: 2012 (105) current year: 2012 (105) highest month: 2012-02 (105) lowest month: 2012-02 (105) current month: 2012-02 (105) highest week: 2012-02-26 (55) lowest week: 2012-02-19 (50) current week: 2012-02-26 (55) highest day: 2012-02-26 (55) lowest day: 2012-02-24 (0) current day: 2012-02-26 (55) longest on streak: 2 days starting on 2012-02-25 longest off streak: 4 days starting on 2012-02-21 current streak: 2 days starting on 2012-02-25 (on)
that example shows totals, but the
options are available here also.
tracker can generate graphs with the help of gnuplot. the
command will result in a graph popping up in gnuplot's native
the graph command works the same way as the log command. the following command will produce a graph of average tv watching per week.
> tracker graph watchedtv -by-week
in addition to 'date grouping' and 'value type' options, the graph type can be set. the default is a line graph, but tracker can produce bar and point graphs. this command produces a graph of the same data, but as a bar graph.
> tracker graph watchedtv -by-week -bar
if an output filename is provided tracker will save the graph to that file instead of popping up a graph window. tracker determines the image file type from the given filename. the filename must end in '.png' or '.svg'. the following command will create a graph image named 'out.png' in the current directory.
> tracker graph watchedtv -by-week -o out.png
there are some examples of tracker graph images here.
tracker has a little tagging support. tags are shortcuts that let you group metrics together so that they can be selected with one name. for instance if you wanted to group pushups and pullups together, you could tag them with 'workout'.
> tracker addtag workout pushups pullups added tag 'workout' to 'pushups' added tag 'workout' to 'pullups'
then you can get the same records report from above with
> tracker records workout ...
that's all for now.
usage: tracker command [options] [metric [metric..]] commands: general: init initialize a repository list list existing metrics and date ranges undo undo the last modify command used hist list recently used modify commands help show help modify repository: set SETVAL set or increment a value see SETVAL below rm remove occurrences import/export: export export data to csv format this will write to stdout unless -o is given import FILE import data from a csv file with the columns: date,metric,value read from stdin if FILE is '-' reporting: log view log of occurrences cal show calendar records show high and low records streaks show consecutive days with or without occurrences graph draw graph (requires gnuplot) tags: addtag TAG tag given metrics with TAG rmtag TAG untag given metrics with TAG listtags list all tags options: general: -d RANGE specify date range (see RANGE below) -o FILE write graph image or csv export to a file -N limit output to the last N items this only affects the 'streaks', 'log', 'hist' --all select all existing metrics --repo FILE specify a repository filename --min VAL min threshold to count as an occurrence -v, --version show version -h, --help show help date groupings for reports: (these are only used by the 'log' and 'graph' commands) -by-day each day is separate (default) -by-week group weeks together -by-month group months together -by-year group years together -by-full group the full date range together values in reports: -total total values (default) -count count of occurrences -percent percent of days with occurrences -per-day average per day -per-week average per week -per-month average per month -per-year average per year graphs: -line draw a line graph (default) -bar draw a bar graph -point draw a point graph SETVAL: =N set metrics to N +N increment metrics by N -N decrement metrics by N RANGE: DATE only the specified date DATE.. days from the given date until today ..DATE days from the start of the data to the specified date DATE..DATE days between specified dates (inclusive) DATE: YYYY-MM-DD specify a date today specify day is today (default) yesterday specify day is yesterday today-N specify day is N days before today examples: > tracker init initialize the default repository > tracker set -d yesterday jogging =2 set jogging occurrence to 2 for yesterday > tracker set -d today bikecommute +1 increase bikecommute metric by 1 for today > tracker rm bikecommute remove bikecommute occurrence for today > tracker log -d 2012-01-01.. bikecommute show a log of all bikecommute occurrences since jan 1, 2012 > tracker cal -d 2012-01-01.. wastedtime show wastedtime calendars for each month from jan 2012 until the current month