6fc6939eed | ||
---|---|---|
doc | ||
features | ||
tests | ||
.dir-locals.el | ||
.gitignore | ||
CHANGELOG.md | ||
Cask | ||
LICENSE | ||
LICENSE.1 | ||
README.md | ||
TODO.org | ||
chronometrist-common.el | ||
chronometrist-custom.el | ||
chronometrist-diary-view.el | ||
chronometrist-events.el | ||
chronometrist-goals.el | ||
chronometrist-migrate.el | ||
chronometrist-plist-pp.el | ||
chronometrist-queries.el | ||
chronometrist-report-custom.el | ||
chronometrist-report.el | ||
chronometrist-sexp.el | ||
chronometrist-statistics-custom.el | ||
chronometrist-statistics.el | ||
chronometrist-tests.el | ||
chronometrist-time.el | ||
chronometrist-timer.el | ||
chronometrist.el | ||
scratch-test | ||
test.timelog | ||
test2.timelog |
README.md
chronometrist
A time tracker in Emacs with a nice interface
Largely modelled after the Android application, A Time Tracker
-
Benefits
- Extremely simple and efficient to use
- Displays useful information about your time usage
- Support for both mouse and keyboard
- Human errors in tracking are easily fixed by editing a plain text file
- Hooks to let you perform arbitrary actions when starting/stopping tasks
-
Limitations
- No support (yet) for adding a task without clocking into it.
- No support for concurrent tasks.
IMPORTANT: with version v0.3, chronometrist no longer uses timeclock as a dependency and will use its own s-expression-based backend. A command to migrate the timeclock-file, chronometrist-migrate-timelog-file->sexp-file
, is provided.
Differences from timeclock
- Stores data in an s-expression format rather than a line-based one
- Supports attaching tags and arbitrary key-values to time intervals
- Has commands to shows useful summaries
- Has a more useful implementation of hooks (see Hooks)
Installation
You can get chronometrist
from https://framagit.org/contrapunctus/chronometrist/
chronometrist
requires dash.el
Add the Chronometrist directory to your load-path, and (require 'chronometrist)
.
Commands
chronometrist
Run M-x chronometrist
to see your projects, the time you spent on them today, which one is active, and the total time clocked today.
Hit RET
on a project to clock in for it. If it's already clocked in, it will be clocked out, and you'll be prompted for an optional reason. Use M-RET
if you don't want to be asked for a reason.
Whenever you call chronometrist
, the cursor will helpfully be placed on the last activity you clocked out of, or the current activity clocked in.
Alternatively, hit <numeric prefix> RET
anywhere in the buffer to toggle the corresponding project, e.g. C-1 RET
will toggle the project with index 1.
Press l
to view your chronometrist-file
(~/.emacs.d/chronometrist.sexp
by default). Press r
to see a weekly report (see chronometrist-report
)
Running M-x chronometrist
when the Chronometrist buffer is visible will kill it, so the key you bind it to can function as a toggle.
chronometrist
keeps itself updated via an idle timer - no need to frequently press g
to update.
Attaching key values to time intervals (experimental)
Add chronometrist-kv-read
to chronometrist-before-in-functions
and/or chronometrist-before-out-functions
, as you like (see Hooks).
You will now be prompted to enter key-values when you clock in/out. Leave an entry blank to exit the prompt, edit the resulting key-values by hand if required, then press C-c C-c
to accept the key-values (or C-c C-k
to cancel).
chronometrist-report
Run M-x chronometrist-report
(or chronometrist
with a prefix argument of 1, or press r
in the chronometrist
buffer) to see a weekly report.
Press b
to look at past weeks, and f
for future weeks.
Press l
to view your chronometrist-file
, ~/.emacs.d/chronometrist.sexp
by default.
Just like chronometrist
, chronometrist-report
will also toggle the visibilty of the buffer.
chronometrist-report
keeps itself updated via an idle timer - no pressing g
to update.
chronometrist-statistics
Run M-x chronometrist-statistics
(or chronometrist
with a prefix argument of 2) to view statistics.
Press b
to look at past time ranges, and f
for future ones.
Press l
to view your chronometrist-file
, ~/.emacs.d/chronometrist.sexp
by default.
Just like chronometrist
, chronometrist-statistics
will also toggle the visibilty of the buffer.
Customization
See the Customize groups chronometrist
and chronometrist-report
for variables intended to be user-customizable.
Hooks
Chronometrist currently has four hooks -
chronometrist-before-in-functions
chronometrist-after-in-functions
chronometrist-before-out-functions
chronometrist-after-out-functions
As their names suggest, these are 'abnormal' hooks, i.e. the functions they contain must accept arguments. In this case, each function must accept exactly one argument, which is the project which is being started or stopped.
As an example from the author's own init -
(defun my-start-guitar (project)
(when (equal project "Guitar")
(find-file-other-window "~/repertoire.org")))
(add-hook 'chronometrist-before-in-functions 'my-start-guitar)
Another one, prompting the user if they have uncommitted changes in a git repository (assuming they use Magit) -
(autoload 'magit-anything-modified-p "magit")
(defun my-commit-prompt ()
(if (magit-anything-modified-p)
(if (yes-or-no-p "You have uncommitted changes. Really clock out? ")
t
(magit-status)
nil)
t))
(add-hook 'chronometrist-before-out-functions 'my-commit-prompt)
Adding more information
Since v0.3, Chronometrist supports adding additional information to tracked time, in the form of tags and user-defined key-value pairs.
Tags
Tags can be added using the chronometrist-tags-add
function. It can currently be added to any hooks except chronometrist-before-in-functions
.
Key-value pairs
Key-value pairs can be added using the chronometrist-kv-add
function. It can currently be added to any hooks except chronometrist-before-in-functions
. Keys can be any string except "name", "tags", "start", or "end". Values can be any readable Lisp values.
Prompt when exiting Emacs
If you wish to be prompted when you exit Emacs while tracking time, you can use this -
(add-hook 'kill-emacs-query-functions 'chronometrist-query-stop)
Roadmap/Ideas
- Show details for time spent on a project when clicking on a non-zero "time spent" field (in both Chronometrist and Chronometrist-Report buffers).
chronometrist
- Better shortcuts - shortcuts derived from the first alphabet of each project might be nicer.
- Reminder notifications - a common issue with time trackers is that people forget to clock in/out. A potential solution can be to have Emacs remind people (ideally via desktop notifications?) -
- when they haven't clocked in, every X minutes (e.g. 30)
- that they are clocked in, every X minutes (e.g. 30)
- of course, modeline support might help too.
- a user-supplied alist of regular expressions/globs matching a file path and projects could be used to offer that the corresponding project be started for them. e.g. given this alist -
...when I open any file in(("*my-compositions*" . "Composition") ("*.el*" . "Programming") ("*.scm" . "Programming"))
~/my-music/my-compositions/
, I'd be offered to start the "Composition" task. When I open an Emacs Lisp or Scheme file, I'd be asked if I want to start the "Programming" task. (with a variable to not ask and just switch, informing the user when that happens.)- Could also add comments based on the path/extension.
- Instead of a path, could also be the name of a major mode.
- See
buffer-list-update-hook
andbefore-change-functions
- an alternative form could look like this -
((PROJECT :pattern ... :mode ... :computerp) ...)
- :pattern - glob pattern to match paths
- :mode - regular expression to match buffer modes
- :computerp or :emacsp - t if this project (activity) is something you do on a computer/in Emacs (or perhaps, more specifically, the same computer/Emacs instance as the one you run Chronometrist on.). Somewhat implied by the previous arguments. If this is t, Chronometrist will note if the computer has received no events for some time, and clock out of the project. If it's an integer, clock out after that many seconds of computer inactivity.
- Use
make-thread
in v26 or the emacs-async library forchronometrist-entries
/chronometrist-report-entries
- Some way to update buffers every second without making Emacs unusable. (impossible?)
- "Day summary" - for users who use the "reason" feature to note the specifics of their actual work. Combine the reasons together to create a descriptive overview of the work done in the day.
Chronometrist-report
- Show week counter and max weeks; don't scroll past first/last weeks
- Highlight column of current day
- Add support for other locale weeks/weekday names
- Show only certain projects
chronometrist-statistics
- Show range counter and max ranges; don't scroll past first/last time ranges
- activity-specific - average time spent in $TIMEPERIOD, average days worked on in $TIMEPERIOD, current/longest/last streak, % of $TIMEPERIOD, % of active (tracked) time in $TIMEPERIOD, ...
- general - most productive $TIMEPERIOD, GitHub-style work heatmap calendar, ...
- press 1 for weekly stats, 2 for monthly, 3 for yearly
Miscellaneous
- README - add images
- [-] Create test timelog file and UI behaviour tests
- Use for
chronometrist-report-weekday-number-alist
whatever variables likeinitial-frame-alist
use to get that fancy Custom UI for alists. - Multi-timelog-file support?
- inflatable raptor
Contributions and contact
Feedback and MRs very welcome. 🙂 doc/hacking.md contains an introduction to the codebase.
Contact the creator and other Emacs users in the Emacs room on the Jabber network - xmpp:emacs@salas.suchat.org?join (web chat)
(For help in getting started with Jabber, click here)
License
Chronometrist is released under your choice of Unlicense and the WTFPL.
(See files LICENSE and LICENSE.1).
Thanks
wasamasa, bpalmer and #emacs for all their help and support
jwiegley for timeclock.el, which we used as a backend in earlier versions
blandest for helping me with the name
fiete for testing and bug reports