Canrylog

Introduction

Canrylog is a personal time tracking application. It has a few principles:

Installation

Canrylog is not yet on MELPA. It can be installed directly from source:

With straight:

(straight-use-package
 '(canrylog :repo "canrylog/canrylog.el" :host gitlab))

Getting started

Tracking data will be saved into the directory defined by canrylog-repo, which defaults to ~/.canrylog.

The main entry point is canrylog-dispatch. This pops up a list of commands to choose from. Press s to switch to a new task.

Run canrylog-dispatch s again to switch to another task. To clock out, run canrylog-dispatch o — the clocked out state is represented by switching to a Downtime task.

canrylog-dispatch provides entry to various reports that can be done on the tracking data.

Stability

I personally recommend putting canrylog-repo under version control to minimize the risk of losing data.

While the current feature set has minimal risk of data loss (the only modifications done are adding new events and local editing commands where Emacs's undo history is available), I plan to integrate synchronization into Canrylog — automatically merging changes can be finicky.

Concepts

Events

Canrylog's tracking is fundamentally based on switching events. An event denotes the start of a task; the start of another task means the end of the previous task. This model precludes multi-tasking.

The state of not really doing anything in particular is represented by switching to a task representing downtime. This is “Downtime” by default, but can be changed with the variable canrylog-downtime-task.

TODO Tasks

Goals

Canrylog can track weekly goals for different tasks.

To add a goal, go to the dashboard, find the Goals and progress for this week section, then press the Add goal button. Alternatively, call the canrylog-db-add-goal command, which does the same thing. The command prompts for a task to add the weekly goal for, then prompts for how much time you wish to spend on that task per week.

Once done, refresh the dashboard or goals page to see the goal and its progress for this week.

A goal can track multiple tasks. Press on the name of the goal to enter the goal's own page, then use the Add task button to add a task to count under this goal.

Deleting and renaming a goal can both be done from the goal's own page.

TODO Frequency Goals

TODO Tags

Buffer management

Like Helpful, each page has its own buffer.

The number of buffers is controlled by canrylog-max-buffers. When a new buffer is created, if the number of buffers would exceed canrylog-max-buffers, then the oldest buffer would be closed.

Canrylog buffers can be killed in one go with the command canrylog-kill-buffers.

Reference

Views

Dashboard / Main view

The dashboard and entry point. Most features can be used from here. Switch to a task to get started.

Distribution report

Task and tag distribution report for a given day, week, or month.

Export

A page for exporting a task's daily durations to CSV.

An option is also available to show duration stats on Xmrit.

Task list

A list of all tasks, by default sorted by total duration.

Single task

Stats and listing a task's children.

Single tag

Stats for tasks tagged with the tag.

Goal list

A list of current weekly goals and their progress. Goals can be added from here. This can be used to view how you've done in the tracking data for previous weeks, using the current goals.

Pressing on each goal enters the goal's own page.

Single goal

Describes a single goal. The goal can also be edited from this page. This page allows:

  • changing the goal's target duration
  • adding or removing tasks to count for this goal (this does not change the tracking data)
  • deleting the goal itself (this also does not change the tracking data)

There is no undo. The expectation is that you keep a backup of the database yourself. If some undo is desired, restore the backup then call canrylog-db-reload.

TODO Commands

canrylog-dispatch

A prefix command for calling other commands. Notably, p toggles whether switching tasks or clocking out should ask for time or not, saving one step when logging an event that happened after the latest event but before the current moment.

canrylog-db-reload

Disconnect from the database file and reconnect to it again. This ensures we are not holding onto a file handler pointing to a deleted or overwritten file.

canrylog-kill-buffers

Kill all buffers created by Canrylog.

TODO User options

canrylog-downtime-task

A string naming the task that is treated as downtime in some reporting. For example, canrylog-clock-out is simply switching to this task, and the dashboard also displays different buttons based on whether the current task represents downtime or not.

canrylog-max-buffers

The number of Canrylog buffers to keep. If nil, then never clean up old Canrylog buffers.

When a new Canrylog buffer is created, if the total number of Canrylog buffers would exceed this number, then old buffers would be killed.

This is like how Helpful's buffer management works.

TODO Internal functions