README.org

org-onit.el

Introduction

This package provides automated org-clock-in and org-clock-out by adding Doing tag to a heading of an org mode buffer. While the Doing tag appears in an org buffer, Emacs Org mode maintains the task clocking.

You can say “I’m on it!”.

Install

Please put org-onit.el into your load-path.

If you use package.el or other package manager, no necessary to add (require 'org-onit) to your init.el and just call toggle commands org-onit-toggle-doing or org-onit-toggle-auto in an org buffer.

Additional package

It is recommended to install org-bookmark-heading because a normal jump by built-in bookmark.el is not sufficiently accurate for org buffers. org-bookmark-heading provides more precise jumping capability by adding ID property to each org mode heading. org-onit.el will use org-bookmark-heading if available but not mandatory.

Recommend settings

Highly recommended

(with-eval-after-load "org-clock"
  (setq org-clock-out-remove-zero-time-clocks t))

Recommended keybindings

(with-eval-after-load "org"
  (global-set-key (kbd "C-<f11>") 'org-clock-goto)
  (define-key org-mode-map (kbd "<f11>") 'org-onit-toggle-doing)
  (define-key org-mode-map (kbd "M-<f11>") 'org-onit-toggle-auto)
  (define-key org-mode-map (kbd "S-<f11>") 'org-onit-goto-anchor))

Optional settings

You can freely arrange org-clock-frame-title-format. If you install org-clock-toay.el in your system, then you can show a working time only for today.

(with-eval-after-load "org"
  (add-to-list 'org-tag-faces '("Doing" :foreground "#FF0000"))
  (add-hook 'org-cycle-hook #'org-onit-clock-in-when-unfold))

(with-eval-after-load "org-clock"
  (setq org-clock-clocked-in-display 'frame-title) ;; or 'both
  (setq org-clock-frame-title-format
        '((:eval (format "%s|%s| %s"
                         (if org-onit--auto-clocking "Auto " "")
                         (org-onit-get-sign)
                         org-mode-line-string)))))

How to use

Manual approach

If you apply the above recommended keybindings, then just type <f11> in an org buffer. A tag of a heading having the cursor will be changed to Doing and automatically start to org-clock-in. You can go any buffers and do anything but you can go back to the Doing tagged heading by just typing C-<f11>. Typing <f11> again, then org-clock-out is executed and Doing tag will disappear. When you type S-<f11>, you can go back to the original position you are jumped from.

clock-in and clock-out triggers

clock-in triggers

org-clock-in will be called when:

• calling org-onit-toggle-doing if the task is not DONE
• calling org-onit-toggle-doing at any headings if :wakeup of org-onit-basic-options is doing or both
• unfolding a heading if :unfold of org-onit-basic-options is non-nil

clock-out triggers

org-clock-out will be called when:

• calling org-onit-toggle-doing
• making the task DONE or removing todo state

Automated approach

Use M-x org-onit-toggle-auto. Toggling org-clock-in and org-clock-out will be done automatically no need to toggle Doing tag by yourself.

clock-in and clock-out triggers

clock-in triggers

org-clock-in will be called when:

• visiting a heading if the task is not DONE
• visiting a heading if :nostate of org-onit-basic-options is auto or both and the task is not DONE
• making the task not DONE

clock-out triggers

org-clock-out will be called when:

• switching to other headings if the task has a todo state (e.g. TODO)
• switching to other headings if :nostate of org-onit-basic-options= is auto or both and the task is not DONE
• making the task DONE
• calling org-onit-toggle-doing

Options

• org-onit-wakeup-done (deprecated, use org-onit-basic-options)
  • Allow switching to org-clock-in by org-onit-toggle-doing when the heading is DONE.
  • Default: nil
• org-onit-include-no-state-heading (deprecated, use org-onit-basic-options)
  • Allow switching to org-clock-in in any headings except headings in TODO when org-onit-toggle-auto is used
  • Default: nil
• org-onit-basic-options
  • This variable is buffer-local. Please use setq-default or custom-set-variables in your init.el.
  • :wakeup allows switching to org-clock-in when the heading is DONE.
  • :nostate allows switching to org-clock-in in any headings except headings in TODO
  • :unfold allows switching to org-clock-in when unfolding a heading
  • Default: (:wakeup nil :nostate nil :unfold nil)
    • :wakeup and :nostate can take doing, auto, both, and nil
      • If doing is specified, the option will be used in org-onit-toggle-doing
      • If auto is specified, the option will be used in org-onit-toggle-auto
      • If both is specified, the option will be used in org-onit-toggle-doing and org-onit-toggle-auto
    • :unfold can take t or nil
      • But :wakeup and :nostate are given priority over :unfold
• org-onit-encure-clock-out-when-exit
  • Call org-clock-out when killing Emacs if org-clock-persis is not history or nil
  • Default: t
• org-onit-keep-no-state
  • If non-nil, allow clocking in but keep the heading TODO state none
  • If nil and :nostate of org-onit-basic-options is specified as non-nil, then the subtree will be changed to TODO heading state and clock-in
  • Default: t

Helpers

• org-onit-update-options

  org-onit-basic-options ;; (:wakeup nil :nostate nil :unfold nil)
  (org-onit-update-options '(:nostate doing :unfold t)) ;; update the local variable
  org-onit-basic-options ;; (:wakeup nil :nostate doing :unfold t)
      

Hooks

• org-onit-switch-task-hook
• org-onit-start-autoclock-hook
• org-onit-stop-autoclock-hook
• org-onit-after-jump-hook

  (defun my-onit-reveal ()
    (org-reveal)
    (org-cycle-hide-drawers 'all)
    (org-show-entry)
    (show-children)
    (org-show-siblings))
  (add-hook 'org-onit-after-jump-hook #'my-onit-reveal)
      

Contribution

Require tools for testing

• cask
  • install via brew

    brew install cask
            

  • manual install

    cd ~/
    hub clone cask/cask
    export PATH="$HOME/.cask/bin:$PATH"
            

Running test

Below operation flow is recommended.

make                              # Install git-hooks in local .git

git branch [feature-branch]       # Create branch named [feature-branch]
git checkout [feature-branch]     # Checkout branch named [feature-branch]

# <edit loop>
emacs org-onit.el                 # Edit something you want

make test                         # Test org-onit
git commit -am "brabra"           # Commit (auto-run test before commit)
# </edit loop>

hub fork                          # Create fork at GitHub
git push [user] [feature-branch]  # Push feature-branch to your fork
hub pull-request                  # Create pull-request

ChangeLog

• 1.0.7 (2019-09-30)
  • [new] org-onit-update-options is added to update org-onit-basic-options
  • [deprecated] org-onit-toggle-options will be org-onit-basic-options
• 1.0.6 (2019-09-29)
  • [improved] Make org-onit-toggle-options buffer local
• 1.0.5 (2019-09-26)
  • [new] org-onit-clock-in-when-unfold is now public function
• 1.0.4 (2019-09-25)
  • [new] org-onit-keep-no-state is added
• 1.0.3 (2019-09-24)
  • [improved] org-onit-use-unfold-as-doing is integrated to org-onit-toggle-options
  • [deprecated] org-onit-use-unfold-as-doing
• 1.0.2 (2019-09-12)
  • [new] org-onit-toggle-options is introduced
  • [improved] org-clock-in-switch-to-state is reflected to org-onit-todo-state
  • [deprecated] org-onit-wakeup-done
  • [deprecated] org-onit-include-no-state-heading
• 1.0.1 (2019-09-01)
  • [improved] Rename “todo status” to “todo state”
  • [breaking change] rename to org-onit-include-no-state-heading
  • [new] support to clock-out when removing todo state
• 1.0.0 (2019-09-01)
  • initial release