Largely modelled after the Android application, [[https://github.com/netmackan/ATimeTracker][A Time Tracker]]
** Benefits
1. Extremely simple and efficient to use
2. Displays useful information about your time usage
3. Support for both mouse and keyboard
4. Human errors in tracking are easily fixed by editing a plain text file
5. Hooks to let you perform arbitrary actions when starting/stopping tasks
** Limitations
1. No support (yet) for adding a task without clocking into it.
2. No support for concurrent tasks.
** Comparisons
:PROPERTIES:
:CUSTOM_ID: comparisons
:END:
*** timeclock.el
:PROPERTIES:
:CUSTOM_ID: timeclock.el
:END:
Compared to timeclock.el, Chronometrist
+ 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 more hooks (see [[#Hooks][Hooks]])
*** Org time tracking
:PROPERTIES:
:CUSTOM_ID: org-time-tracking
:END:
Chronometrist and Org time tracking seem to be equivalent in terms of capabilities, approaching the same ends through different means.
+ Chronometrist doesn't have a mode line indicator at the moment. (planned)
+ Chronometrist doesn't have Org's sophisticated querying facilities. (an SQLite backend is planned)
+ Org does so many things that keybindings seem to necessarily get longer. Chronometrist has far fewer commands than Org, so most of the keybindings are single keys, without modifiers.
+ Chronometrist's UI makes keybindings discoverable - they are displayed in the buffers themselves.
+ Chronometrist's UI is cleaner, since the storage is separate from the display. It doesn't show tasks as trees like Org, but it uses tags and key-values to achieve that. Additionally, navigating a flat list takes fewer user operations than navigating a tree.
+ Chronometrist data is just s-expressions (plists), and may be easier to parse than a complex text format with numerous use-cases.
** Installation
:PROPERTIES:
:CUSTOM_ID: installation
:END:
*** from MELPA
:PROPERTIES:
:CUSTOM_ID: from-melpa
:END:
1. Set up MELPA - https://melpa.org/#/getting-started
(Chronometrist uses semantic versioning and only releases are pushed to the master branch, so using MELPA Stable is recommended and has no effect on frequency of updates.)
You can also 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 =r= to see a weekly report (see =chronometrist-report=)
*** chronometrist-report
:PROPERTIES:
:CUSTOM_ID: chronometrist-report
:END:
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.
*** chronometrist-statistics
:PROPERTIES:
:CUSTOM_ID: chronometrist-statistics
:END:
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.
*** chronometrist-details
*** common commands
In the buffers created by the previous three commands, you can press =l= (=chronometrist-open-log=) to view/edit your =chronometrist-file=, which by default is =~/.emacs.d/chronometrist.sexp=.
All of these commands will kill their buffer when run again with the buffer visible, so the keys you bind them to behave as a toggle.
Part of the reason Chronometrist stores time intervals as property lists is to allow you to add tags and arbitrary key-values to them.
**** Tags
:PROPERTIES:
:CUSTOM_ID: tags
:END:
To be prompted for tags, add =chronometrist-tags-add= to any hook except =chronometrist-before-in-functions=, based on your preference (see [[#Hooks][Hooks]]). The prompt suggests past combinations you used for the current task, which you can browse with =M-p=/=M-n=. You can leave it blank by pressing =RET=, or skip the prompt just this once by pressing =M-RET= (=chronometrist-toggle-task-no-hooks=).
**** Key-value pairs
:PROPERTIES:
:CUSTOM_ID: key-value-pairs
:END:
Similarly, to be prompted for key-values, add =chronometrist-kv-add= to any hook except =chronometrist-before-in-functions=. To exit the prompt, press the key it indicates for quitting - you can then edit the resulting key-values by hand if required. Press =C-c C-c= to accept the key-values, or =C-c C-k= to cancel.
*** Prompt when exiting Emacs
:PROPERTIES:
:CUSTOM_ID: prompt-when-exiting-emacs
:END:
If you wish to be prompted when you exit Emacs while tracking time, you can use this -
If you wish you could define time goals for some tasks, and have Chronometrist notify you when you're approaching the goal, completing it, or exceeding it, check out the extension [[https://github.com/contrapunctus-1/chronometrist-goal/][chronometrist-goal.el]].
See the Customize groups =chronometrist= and =chronometrist-report= for variables intended to be user-customizable.
*** Hooks
:PROPERTIES:
:CUSTOM_ID: hooks
:END:
Chronometrist currently has the following hooks -
1.=chronometrist-mode-hook=
2.=chronometrist-before-in-functions=
3.=chronometrist-after-in-functions=
4.=chronometrist-before-out-functions=
5.=chronometrist-after-out-functions=
6.=chronometrist-list-format-transformers=
7.=chronometrist-entry-transformers=
8.=chronometrist-file-change-hook=
The hooks whose names end with =-functions= are abnormal hooks - each function must accept exactly one argument, which is the name of the project which is being started or stopped, as a string.
=chronometrist-before-out-functions= is different from the other three, in that it runs until failure - the task will be clocked out only if all functions in this hook return =t=.
If you have tried using Chronometrist, I'd love to hear your experiences! Get in touch with the author and other Emacs users in the Emacs channel on the Jabber network - [[https://conversations.im/j/emacs@salas.suchat.org][xmpp:emacs@salas.suchat.org?join]] ([[https://inverse.chat/#converse/room?jid=emacs@salas.suchat.org][web chat]])
(For help in getting started with Jabber, [[https://xmpp.org/getting-started/][click here]])
** License
:PROPERTIES:
:CUSTOM_ID: license
:END:
I dream of a world where all software is liberated - transparent, trustable, and accessible for anyone to use or improve. But I don't want to make demands or threats (e.g.via legal conditions) to get there.
I'd rather make a request - please do everything you can to help that dream come true. Please Unlicense as much software as you can.
Chronometrist is released under your choice of [[https://unlicense.org/][Unlicense]] or the [[http://www.wtfpl.net/][WTFPL]].
(See files [[file:UNLICENSE]] and [[file:WTFPL]]).
** Thanks
:PROPERTIES:
:CUSTOM_ID: thanks
:END:
wasamasa, bpalmer, aidalgol, pjb and the rest of #emacs for their tireless help and support
jwiegley for timeclock.el, which we used as a backend in earlier versions