Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/unhammer/org-mru-clock

⏲️ Effortlessly clock in/out of org-mode tasks, with completion and persistent history
https://github.com/unhammer/org-mru-clock

emacs helm ivy org-mode pomodoro productivity time-management

Last synced: about 2 months ago
JSON representation

⏲️ Effortlessly clock in/out of org-mode tasks, with completion and persistent history

Awesome Lists containing this project

README 

        
#+TITLE: org-mru-clock



[[https://melpa.org/#/org-mru-clock][https://melpa.org/packages/org-mru-clock-badge.svg]]

[[https://stable.melpa.org/#/org-mru-clock][https://stable.melpa.org/packages/org-mru-clock-badge.svg]]



Do you often clock in to many different little tasks? Are you annoyed

that you can't just clock in to one of your most recent tasks after

restarting Emacs?



#+ATTR_HTML: :alt org-mru-clock demo

[[file:org-mru-clock.gif][file:org-mru-clock.gif]]



The function =org-mru-clock-in= from this package will pre-fill your

clock history with clocks from your agenda files (and other open org

files) so you can clock in to your most recent clocks regardless of

whether you just started Emacs or have had it running for

decades. Tasks are sorted by recency, and uses completing-read for

quick selection. This makes it a nice replacement for

=org-clock-in-last=.



It uses =completing-read-function= (overridable with

=org-mru-clock-completing-read=) on =org-mru-clock-in= to make

clocking in faster. If you set that to =ivy-completing-read=, you can

hit =M-o g= to visit to the task heading instead of clocking in (there

are also Embark actions if you prefer that – see [[*Manual, loading on startup:][Usage]]).



The list is sorted to keep the most recently clocked entry first,

although if the entry at point is an org-mode heading (in an org file

or the agenda), then that will be pushed to the top of the list (you

can turn off this behaviour by setting

=org-mru-clock-include-entry-at-point= to =nil=).



You can also use =org-mru-clock-select-recent-task= as a replacement

for =org-clock-select-task=, again with pre-filled history.



You may also capture new tasks on the fly if your search text didn't

match anything – try =C-h v org-mru-clock-capture-if-no-match RET=.



* Installation



** MELPA

If you use [[https://melpa.org/][MELPA]], you can just do =M-x list-packages=, find

=org-mru-clock= in the list and hit =i x=.



** Manual

Just put =org-mru-clock.el= somewhere in =load-path=.



* Usage



** Manual, loading on startup:



To use, require and bind whatever keys you prefer to the

interactive functions:



#+BEGIN_SRC emacs-lisp

(require 'org-mru-clock)

(global-set-key (kbd "C-c C-x i") #'org-mru-clock-in)

(global-set-key (kbd "C-c C-x C-j") #'org-mru-clock-select-recent-task)

#+END_SRC



Maybe trade some initial slowness for more tasks cached:



#+BEGIN_SRC emacs-lisp

(setq org-mru-clock-how-many 100)

#+END_SRC



But don't set it higher than the actual number of tasks; then

it'll always try (and fail) to fill up the history cache!



If you want to use ivy for =org-mru-clock-in=:



#+BEGIN_SRC emacs-lisp

(setq org-mru-clock-completing-read #'ivy-completing-read)

#+END_SRC



If you use the [[https://github.com/oantolin/embark/][embark]] package, you can add actions with:



#+BEGIN_SRC emacs-lisp

(add-hook 'minibuffer-setup-hook #'org-mru-clock-embark-minibuffer-hook)

#+END_SRC



** With use-package



If you prefer =use-package=, the above settings would be:



#+BEGIN_SRC emacs-lisp

(use-package org-mru-clock

  :ensure t

  :bind* (("C-c C-x i" . org-mru-clock-in)

          ("C-c C-x C-j" . org-mru-clock-select-recent-task))

  :config

  (setq org-mru-clock-how-many 100

        org-mru-clock-completing-read #'ivy-completing-read)

  (add-hook 'minibuffer-setup-hook #'org-mru-clock-embark-minibuffer-hook))

#+END_SRC



** Other org-mru-clock settings



If you do

#+BEGIN_SRC emacs-lisp

  (setq org-mru-clock-keep-formatting t)

#+END_SRC

then entries will be shown in their org-mode faces, instead of

whatever face your =org-mru-clock-completing-read= function uses by

default.



If you do

#+BEGIN_SRC emacs-lisp

  (setq org-mru-clock-include-entry-at-point nil)

#+END_SRC

then the entry at point will /not/ be prepended to the start of the

list.



By default, all open =org-mode= files are searched for recent clocks,

but you can change this to e.g. only the =org-agenda-files= with

#+BEGIN_SRC emacs-lisp

  (setq org-mru-clock-files #'org-agenda-files)

#+END_SRC

or some other function of your own devising.



You can also exclude clocks by setting =org-mru-clock-predicate= to

e.g. =org-entry-is-todo-p= (which will exclude DONE tasks) or

=org-mru-clock-exclude-done-and-archived= (which will also exclude

those tagged with =org-archive-tag=).



** Related settings from org-clock



You may also be interested in these general org-clock settings

([[http://orgmode.org/manual/Clocking-work-time.html][documented]] in the Org-mode manual):



#+BEGIN_SRC emacs-lisp

(setq org-clock-persist t)

(org-clock-persistence-insinuate)

#+END_SRC