Skip to content

Latest commit

 

History

History
215 lines (167 loc) · 8.68 KB

README.org

File metadata and controls

215 lines (167 loc) · 8.68 KB

org-onit.el

https://github.com/takaxp/org-onit/workflows/Main%20workflow/badge.svg

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!”.

https://github.com/takaxp/contents/blob/master/org-onit/org-onit-toggle-doing.png

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