Org Mode - Organize Your Life In Plain Text!

The following setup in my .emacs enables org-mode for most buffers. org-mode is the default mode for .org, .org_archive, and .txt files.

;;;
;;; Org Mode
;;;
(add-to-list 'load-path (expand-file-name "~/git/org-mode/lisp"))
(add-to-list 'auto-mode-alist '("\\.\\(org\\|org_archive\\|txt\\)$" . org-mode))
(require 'org-install)
;;
;; Standard key bindings
(global-set-key "\C-cl" 'org-store-link)
(global-set-key "\C-ca" 'org-agenda)
(global-set-key "\C-cb" 'org-iswitchb)

orgstruct++-mode is enabled in Gnus message buffers to aid in creating structured email messages.

(setq message-mode-hook
      (quote (orgstruct++-mode
              (lambda nil (setq fill-column 72) (flyspell-mode 1))
              turn-on-auto-fill
              bbdb-define-all-aliases)))

flyspell-mode is enabled for almost everything to help prevent creating documents with spelling errors. yasnippets are enabled to speed up creation of standard text blocks in most editing modes.

;; Make TAB the yas trigger key in the org-mode-hook and turn on flyspell mode
(add-hook 'org-mode-hook
          (lambda ()
            ;; yasnippet
            (make-variable-buffer-local 'yas/trigger-key)
            (setq yas/trigger-key [tab])
            (define-key yas/keymap [tab] 'yas/next-field-group)
            ;; flyspell mode to spell check everywhere
            (flyspell-mode 1)))

Tasks are separated into logical groupings or projects. Use separate org files for large task groupings.

Here are sample files that I use.

The following org files collect non-work related tasks:

Filename	Description
todo.org	Personal tasks and things to keep track of
gsoc2009.org	Google Summer of Code stuff for 2009
farm.org	Farm related tasks
mark.org	Tasks related to my son Mark
org.org	Org-mode related tasks
git.org	Git related tasks
bzflag.org	BZFlag related tasks

The following org-file collects remember notes and tasks:

Filename	Description
refile.org	Remember task bucket

The following work-related org-files keep my business notes (using fictitious client names)

Filename	Description
norang.org	Norang tasks and notes
XYZ.org	XYZ Corp tasks and notes
ABC.org	ABC Ltd tasks
ABC-DEF.org	ABC Ltd tasks for their client DEF Corp
ABC-KKK.org	ABC Ltd tasks for their client KKK Inc
YYY.org	YYY Inc tasks

Org-mode is great for dealing with multiple clients and client projects. An org file becomes the collection of projects, notes, etc. for a single client or client-project.

Clients (ABC Ltd) has multiple customer systems that I work on. Separating the tasks for each client-customer into separate org files helps keep things logically grouped and since clients come and go this allows entire org files to be added or dropped from my agenda to keep only what is important visible in agenda views.

Other org files are used for publishing only and do not contribute to the agenda. See Publishing for more details.

Here is my current org-agenda-files setup. It is shown above formatted as a setq for clarity but in reality this is saved in my custom.el file.

(setq org-agenda-files (quote ("~/git/org/refile.org"
                               "~/git/org/gsoc2009.org"
                               "~/git/org/farm.org"
                               "~/git/org/mark.org"
                               "~/git/org/org.org"
                               "~/git/org/norang.org"
                               ; client org files removed
                               "~/git/org/git.org"
                               "~/git/org/todo.org"
                               "~/git/org/bzflag.org"
                               "~/git/org/diary.org")))

org-mode manages the org-agenda-files variable. I just visit an org file and add it to the agenda with C-c [. To remove a file I just visit it and hit C-c ] and all of the tasks in that file are instantly removed from my agenda views until I add them back again.

Most of my org files are set up with level 1 headings as main categories only. Tasks normally start as level 2.

Here are some examples of my level 1 headings in

todo.org:

• Appointments
• Special Dates

  Includes level 2 headings for

  • Birthdays
  • Anniversaries
  • Holidays
• Finances
• Health
• House Maintenance
• Medical
• Miscellaneous
• Lawn and Garden

norang.org:

• System Maintenance
• Payroll
• Accounting
• Finances
• Hardware Maintenance
• Quotes
• Administration
• Research

Each of these level 1 tasks normally has a property drawer specifying the archive location and category for any tasks in that tree. Level 1 headings are set up like this:

* Appointments
  :PROPERTIES:
  :CATEGORY: Appt
  :ARCHIVE:  %s_archive::* Appointments
  :END:      
  ...
* Miscellaneous
  :PROPERTIES:
  :CATEGORY: todo
  :ARCHIVE: %s_archive::* Miscellaneous
  :END:

This ensures that any level 2 task that I archive from this heading (I archive by subtree) gets saved in the archive file under the appropriate level 1 heading so I can find it back again if needed.

This keeps my main org files and my archives with basically the same structure.

I live in the agenda. To make getting to the agenda faster I mapped F12 to the sequence C-c a since I'm using it hundreds of times a day.

I have the following custom key bindings set up for my emacs (sorted by frequency).

Key	For	Used
F12	Agenda (1 key less than C-c a)	Very Often
C-c b	Switch to org file	Very Often
C-F11	Clock in a task (show menu with prefix)	Very Often
f9 g	Gnus - I live in gnus	Often
C-M-r	Create a remember task	Often
F11	Goto currently clocked item	Often
f5	Show todo items for this subtree	Often
S-f5	Widen	Often
f9 b	Quick access to bbdb data	Often
f9 c	Calendar access	Often
f9 r	Boxquote selected region	Often
C-S-f12	Save buffers and publish current project	Often
C-c l	Store a link for retrieval with C-c C-l	Often
f9 m	Clock in read mail and news task	Often
f9 o	Clock in organization task	Often
f8	Go to next org file in org-agenda-files	Sometimes
f9 t	Insert inactive timestamp	Sometimes
f9 v	Toggle visible mode (for showing/editing links)	Sometimes
C-f9	Previous buffer	Sometimes
C-f10	Next buffer	Sometimes
C-x n r	Narrow to region	Sometimes
f9 f	Boxquote insert a file	Sometimes
f9 i	Org-mode Info manual	Sometimes
f9 O	Clock out	Sometimes
f9 s	Switch to scratch buffer	Sometimes
f9 h	Hide other tasks	Rare
f7	Toggle line truncation/wrap	Rare
f9 u	Untabify region	Rare
C-c a	Enter Agenda (minimal emacs testing)	Rare
M-f11	Resolve open clocks	Rare

Here is the keybinding setup in lisp:

;; Custom Key Bindings
(global-set-key (kbd "<f12>") 'org-agenda)
(global-set-key (kbd "<f5>") 'bh/org-todo)
(global-set-key (kbd "<S-f5>") 'widen)
(global-set-key (kbd "<f7>") 'set-truncate-lines)
(global-set-key (kbd "<f8>") 'org-cycle-agenda-files)
(global-set-key (kbd "<f9> b") 'bbdb)
(global-set-key (kbd "<f9> c") 'calendar)
(global-set-key (kbd "<f9> f") 'boxquote-insert-file)
(global-set-key (kbd "<f9> g") 'gnus)
(global-set-key (kbd "<f9> h") 'hide-other)
(global-set-key (kbd "<f9> i") (lambda ()
                                 (interactive)
                                 (info "~/git/org-mode/doc/org.info")))
(global-set-key (kbd "<f9> m") 'bh/clock-in-read-mail-and-news-task)
(global-set-key (kbd "<f9> o") 'bh/clock-in-organization-task)
(global-set-key (kbd "<f9> O") 'org-clock-out)
(global-set-key (kbd "<f9> r") 'boxquote-region)
(global-set-key (kbd "<f9> s") (lambda () (interactive) (switch-to-buffer "*scratch*") (delete-other-windows)))
(global-set-key (kbd "<f9> t") 'bh/insert-inactive-timestamp)
(global-set-key (kbd "<f9> u") (lambda ()
                                 (interactive)
                                 (untabify (point-min) (point-max))))
(global-set-key (kbd "<f9> v") 'visible-mode)
(global-set-key (kbd "<f9> SPC") 'bh/clock-in-interrupted-task)
(global-set-key (kbd "C-<f9>") 'previous-buffer)
(global-set-key (kbd "C-x n r") 'narrow-to-region)
(global-set-key (kbd "C-<f10>") 'next-buffer)
(global-set-key (kbd "<f11>") 'org-clock-goto)
(global-set-key (kbd "C-<f11>") 'org-clock-in)
(global-set-key (kbd "C-s-<f12>") 'bh/save-then-publish)
(global-set-key (kbd "M-<f11>") 'org-resolve-clocks)
(global-set-key (kbd "C-M-r") 'org-remember)

The main reason I have special key bindings (like F11, and F12) is so that the keys work in any mode. If I'm in the Gnus summary buffer then C-u C-c C-x C-i doesn't work, but the C-F11 key combination does and this saves me time since I don't have to visit an org-mode buffer first just to clock in a recent task.

Here are my TODO state keywords and colour settings:

(setq org-todo-keywords (quote ((sequence "TODO(t)" "STARTED(s!)" "|" "DONE(d!/!)")
 (sequence "WAITING(w@/!)" "SOMEDAY(S!)" "OPEN(O@)" "|" "CANCELLED(c@/!)")
 (sequence "QUOTE(q!)" "QUOTED(Q!)" "|" "APPROVED(A@)" "EXPIRED(E@)" "REJECTED(R@)"))))

(setq org-todo-keyword-faces (quote (("TODO" :foreground "red" :weight bold)
 ("STARTED" :foreground "blue" :weight bold)
 ("DONE" :foreground "forest green" :weight bold)
 ("WAITING" :foreground "orange" :weight bold)
 ("SOMEDAY" :foreground "magenta" :weight bold)
 ("CANCELLED" :foreground "forest green" :weight bold)
 ("QUOTE" :foreground "red" :weight bold)
 ("QUOTED" :foreground "magenta" :weight bold)
 ("APPROVED" :foreground "forest green" :weight bold)
 ("EXPIRED" :foreground "forest green" :weight bold)
 ("REJECTED" :foreground "forest green" :weight bold)
 ("OPEN" :foreground "blue" :weight bold))))

Fast todo selection allows changing from any task todo state to any other state directly by selecting the appropriate key from the fast todo selection key menu. This is a great feature!

(setq org-use-fast-todo-selection t)

Changing a task state is done with

C-c C-t KEY

where KEY is the appropriate fast todo state selection key as defined in org-todo-keywords.

The setting

(setq org-treat-S-cursor-todo-selection-as-state-change nil)

allows changing todo states with S-left and S-right skipping all of the normal processing when entering or leaving a todo state. This cycles through the todo states but skips setting timestamps and entering notes which is very convenient when all you want to do is fix up the status of an entry.

I have a few triggers that automatically assign tags to tasks based on state changes. If a task moves to CANCELLED state then it gets a CANCELLED tag. Moving a CANCELLED task back to TODO removes the CANCELLED tag. These are used for filtering tasks in agenda views which I'll talk about later.

The triggers break down to the following rules:

• Moving a task to CANCELLED adds a CANCELLED tag
• Moving a task to WAITING adds a WAITING tag and removes any NEXT tag
• Moving a task to SOMEDAY adds a WAITING tag
• Moving a task to a done state removes NEXT and WAITING tags
• Moving a task to TODO removes WAITING, CANCELLED, and NEXT tags
• Moving a task to DONE removes WAITING, CANCELLED, and NEXT tags

The tags are used to filter tasks in the agenda views conveniently.

(setq org-todo-state-tags-triggers
      (quote (("CANCELLED" ("CANCELLED" . t))
              ("WAITING" ("WAITING" . t) ("NEXT"))
              ("SOMEDAY" ("WAITING" . t))
              (done ("NEXT") ("WAITING"))
              ("TODO" ("WAITING") ("CANCELLED") ("NEXT"))
              ("STARTED" ("WAITING"))
              ("DONE" ("WAITING") ("CANCELLED") ("NEXT")))))

;; Change task state to STARTED from TODO when clocking in
(defun bh/clock-in-to-started (kw)
  "Switch task from TODO to STARTED when clocking in"
  (if (string-equal kw "TODO")
      "STARTED"
    nil))

(setq org-clock-in-switch-to-state (quote bh/clock-in-to-started))

When a new task needs to be added I categorize it into one of three things:

• A phone call
• A new task
• A new note

and pick the appropriate remember task.

Here is my setup for org-remember

(setq org-default-notes-file "~/git/org/refile.org")

;;;  Load Org Remember Stuff
(require 'remember)
(org-remember-insinuate)

;; I use C-M-r to start org-remember
(global-set-key (kbd "C-M-r") 'org-remember)

;; Keep clocks running
(setq org-remember-clock-out-on-exit nil)

;; C-c C-c stores the note immediately
(setq org-remember-store-without-prompt t)

;; I don't use this -- but set it in case I forget to specify a location in a future template
(setq org-remember-default-headline "Tasks")

;; 3 remember templates for TODO tasks, Notes, and Phone calls
(setq org-remember-templates (quote (("todo" ?t "* TODO %?\n  %u\n  %a" nil bottom nil)
                                     ("note" ?n "* %?                                        :NOTE:\n  %U\n  %a" nil bottom nil)
                                     ("phone" ?p "* PHONE %:name - %:company -                :PHONE:\n  Contact Info: %a\n  %u\n  %?" nil bottom nil)
                                     ("appointment" ?a "* %?\n  %U" "~/git/org/todo.org" "Appointments" nil)
                                     ("org-protocol" ?w "* TODO Review %c%!\n  %U" nil bottom nil))))

I have a single org file which is the target for my remember templates.

I store notes, tasks, phone calls, and org-protocol tasks in refile.org. I used to use multiple files but found that didn't really have any advantage over a single file.

Normally this file is empty except for a single line at the top which creates a REFILE tag for anything in the file.

The file has a single permanent line at the top like this

#+FILETAGS: REFILE

Okay I'm in the middle of something and oh yeah - I have to remember to do that. I don't stop what I'm doing. I'm probably clocking a project I'm working on and I don't want to lose my focus on that but I can't afford to forget this little thing that just came up.

So what do I do? Hit C-M-r to start remember mode and select t since it's a new task and I get a buffer like this

##     C-c C-c  "~/git/org/refile.org" -> "* bottom"
## C-u C-c C-c  like C-c C-c, and immediately visit note at target location
## C-0 C-c C-c  "???" -> "* ???"
## C-1 C-c C-c  to select file and header location interactively.
## C-2 C-c C-c  as child of the currently clocked item
## To switch templates, use `C-M-r'.  To abort use `C-c C-k'.

* TODO 
  [2009-04-19 Sun]
  [[file:~/git/doc.norang.ca/org-mode.org::*Remember%20Tasks%20is%20all%20about%20begin%20FAST][file:~/git/doc.norang.ca/org-mode.org::*Remember Tasks is all about begin FAST]]

Enter the details of the TODO item and C-c C-c to file it away in refile.org and go right back to what I'm really working on secure in the knowledge that that item isn't going to get lost and I don't have to think about it anymore at all now.

To refile tasks in org you need to tell it where you want to refile things.

In my setup I let any file in org-agenda-files and the current file contribute to the list of valid refile targets. I don't refile to tasks more then 5 levels deep just to limit the number of displayed targets. I also use ido to help find targets quickly.

Here is my refile configuration:

; Use IDO for target completion
(setq org-completion-use-ido t)

; Targets include this file and any file contributing to the agenda - up to 5 levels deep
(setq org-refile-targets (quote ((org-agenda-files :maxlevel . 5) (nil :maxlevel . 5))))

; Targets start with the file name - allows creating level 1 tasks
(setq org-refile-use-outline-path (quote file))

; Targets complete in steps so we start with filename, TAB shows the next level of targets etc
(setq org-outline-path-complete-in-steps t)

; Allow refile to create parent tasks with confirmation
(setq org-refile-allow-creating-parent-nodes (quote confirm))

To refile a task to my norang.org file under System Maintenance I just put the cursor on the task and hit C-c C-w and enter nor TAB sys TAB RET and it's done. I always know what file it's going into but if I don't remember the exact task name I can just hit TAB twice and all remember targets that match show up in a list. Just scroll through the list and pick the right refile target. This works great!

To find tasks to refile I run my agenda view (F12 r = C-c a r) which shows tasks with the REFILE tag. This view shows all tasks (even ones marked in a done state).

All of my remember target files have this tag in the FILETAGS header so every task in the file can be found using this view.

I visit each file with REFILE tasks to refile. If there are a few files going to the same place (3 or less) I refile the first one, then move to the second one and use C-c C-w up-arrow RET to refile to the same location again. If more than 3 tasks are going to the same place I try to do those last - since refiling everything else away helps to group those together. Then I select the group of tasks and refile them in a single operation.

Refiling all of my tasks tends to take less than a minute so I may do this a couple of times a day.

I keep a * Notes headline in most of my org-mode files. Notes have a NOTE tag which is created by the remember template for notes. This allows finding notes across multiple files easily using the agenda search functions.

Notes created by remember tasks go first to refile.org and are later refiled to the appropriate project file. Some notes that are project related get filed to the appropriate project instead of under the catchall * NOTES task. Generally these types of notes are specific to the project and not generally useful – so removing them from the notes list when the project is archived makes sense.

Phone calls are handled the same as notes. I time my calls, creating them with F12 p and filing them in refile.org. Later these are refiled to a * Phone Calls task or to the project task that this clocked phone call should contribute clocked time to. Some phone calls are billable and we want these tracked in the appropriate category.

(setq org-agenda-custom-commands
      (quote (("s" "Started Tasks" todo "STARTED" ((org-agenda-todo-ignore-scheduled nil)
                                                   (org-agenda-todo-ignore-deadlines nil)
                                                   (org-agenda-todo-ignore-with-date nil)))
              ("w" "Tasks waiting on something" tags "WAITING/!" ((org-use-tag-inheritance nil)))
              ("r" "Refile New Notes and Tasks" tags "LEVEL=1+REFILE" ((org-agenda-todo-ignore-with-date nil)
                                                                       (org-agenda-todo-ignore-deadlines nil)
                                                                       (org-agenda-todo-ignore-scheduled nil)))
              ("N" "Notes" tags "NOTE" nil)
              ("n" "Next" tags "NEXT-WAITING-CANCELLED/!" nil)
              ("p" "Projects" tags-todo "LEVEL=2-NEXT-WAITING-CANCELLED/!-DONE" nil)
              ("A" "Tasks to be Archived" tags "LEVEL=2/DONE|CANCELLED" nil)
              ("h" "Habits" tags "STYLE=\"habit\"" ((org-agenda-todo-ignore-with-date nil) (org-agenda-todo-ignore-scheduled nil) (org-agenda-todo-ignore-deadlines nil))))))

My day goes generally like this:

• Look at my agenda F12 a
  • make a note of anything important to deal with today
• Read email and news
  • create notes, and tasks for things that need responses with org-remember
• Check refile tasks and respond to emails
• Look at my agenda and knock off tasks scheduled for today
  • Clock it in (I in the agenda or on the beginning of a task headline – this marks it as STARTED)
  • Work on it until it is DONE or it gets interrupted
• Check today's time log report and refile tasks with clocked time
  • F12 a R - any tasks in refile.org should be moved to the appropriate file
  • F12 r to get to refile tasks
  • Tag files to be filed with m collecting all tasks for the same target
  • Bulk refile the tasks to the target location with B r
  • repeat until the agenda timeclock report has all of the time in project files

Use the agenda view for STARTED tasks to find stuff in progress and things to clock. I clock everything - some tasks are always in a STARTED state (Like Organization, Email News and IRC, etc)

I use these tasks for clocking time while doing these activities and my list of STARTED tasks is normally less than 20 items long.

When I look for a new task to work on I generally hit F12 a to get today's agenda and follow this order:

• Pick something off today's agenda
  • deadline for today (do this first - it's not late yet)
  • deadline in the past (it's already late)
  • deadline that is coming up soon
  • a scheduled task for today (or in the past)
• pick a STARTED task (it's unfinished)
• If you run out of items to work on look for NEXT task in the current context F12 n / RET

To read email I do F12 s C-s email RET I which goes to the agenda view for started tasks, searches for 'email' and clocks it in. Then I go to Gnus and read everything in my inboxes. If there are emails that require a response I use org-remember to create a new task with a heading of 'Respond to <user>' for each one. This automatically links to the email in the task and makes it easy to find later. Some emails are quick to respond to and some take research and a significant amount of time to complete. I clock each one in it's own task just in case I need that clocked time later.

Next, I go to my newly created tasks to be refiled with F12 r and clock in an email task and deal with it. Repeat this until all of the 'Respond to <user>' tasks are marked DONE.

I read email and newgroups in Gnus so I don't separate clocked time for quickly looking at things. If an article has a useful piece of information I want to remember I create a note for it with F12 n and enter the topic and file it. This takes practically no time at all and I know the note is safely filed for later.

So many tasks, so little time. I have hundreds of tasks at any given time (373 right now). There is so much stuff to look at it can be daunting. This is where agenda filtering saves the day.

It's 11:53AM and I'm in work mode just before lunch. I don't want to see tasks that are not work related right now. I also don't want to work on a big project just before lunch… so I need to find small tasks that I can knock off the list.

How do we do this? Get a list of NEXT tasks with F12 n and then narrow it down with filtering. To find tasks to work on I remove tasks I'm not supposed to be working on now with / RET. Then limit to tasks with estimates of 10 minutes or less with / + 1 and I can pick something that fits the minutes I have left before I take off for lunch.

(defun bh/weekday-p ()
  (let ((wday (nth 6 (decode-time))))
    (and (< wday 6) (> wday 0))))

(defun bh/working-p ()
  (let ((hour (nth 2 (decode-time))))
    (and (bh/weekday-p) (or (and (>= hour 8) (<= hour 11))
                           (and (>= hour 13) (<= hour 16))))))

(defun bh/network-p ()
  (= 0 (call-process "/bin/ping" nil nil nil
                     "-c1" "-q" "-t1" "norang.ca")))

(defun bh/org-auto-exclude-function (tag)
  (and (cond
       ((string= tag "@home")
        (bh/working-p))
       ((string= tag "@office")
        (not (bh/working-p)))
       ((or (string= tag "@errand") (string= tag "phone"))
        (let ((hour (nth 2 (decode-time))))
          (or (< hour 8) (> hour 21)))))
       (concat "-" tag)))

(setq org-agenda-auto-exclude-function 'bh/org-auto-exclude-function)

Some tasks are periodic. Things I need to do weekly. Since I clock these tasks in they change to a STARTED state. Cyclic or repeated tasks automatically reschedule to the future and reset the task state back to TODO when they are marked DONE. This removes it from the STARTED agenda view and helps keep the list short. Tasks that I've worked on but won't finish anytime soon can be removed from the STARTED agenda view simply by moving the task state keyword back to TODO.

I like to keep control of the clock separate from task state changes. If I mark a clocked task DONE I want the clock to keep running on that task until I've finished all of the work on it. I tend to mark tasks DONE just before I'm really finished with them. This allows me to enter a note with the DONE state that may take a few minutes to compose and the time spent doing this counts towards clocking on that task.

Keeping the clock running when moving a subtask to a DONE state means clocking continues to apply to the parent task. I can pick the next task from the parent and clock that in without losing a minute or two while I'm deciding what to work on next.

I keep clock times in a :CLOCK: drawer and state changes in a :LOGBOOK: drawer.

I have the following org-mode settings for clocking:

;;
;; Resume clocking tasks when emacs is restarted
(org-clock-persistence-insinuate)
;;
;; Yes it's long... but more is better ;)
(setq org-clock-history-length 28)
;; Resume clocking task on clock-in if the clock is open
(setq org-clock-in-resume t)
;; Change task state to STARTED when clocking in
(setq org-clock-in-switch-to-state "STARTED")
;; Separate drawers for clocking and logs
(setq org-drawers (quote ("PROPERTIES" "LOGBOOK" "CLOCK")))
;; Save clock data in the CLOCK drawer and state changes and notes in the LOGBOOK drawer
(setq org-clock-into-drawer "CLOCK")
;; Sometimes I change tasks I'm clocking quickly - this removes clocked tasks with 0:00 duration
(setq org-clock-out-remove-zero-time-clocks t)
;; Don't clock out when moving task to a done state
(setq org-clock-out-when-done nil)
;; Save the running clock and all clock history when exiting Emacs, load it on startup
(setq org-clock-persist (quote history))
;; Disable auto clock resolution
(setq org-clock-auto-clock-resolution nil)
(setq org-clock-idle-time nil)

I keep two tasks specifically for clocking the time I spend organizing stuff and reading mail and news groups. There tasks are defined as follows in my todo.org file

** Organization
   :PROPERTIES:
   :CLOCK_MODELINE_TOTAL: today
   :ID:       437c2cde-fbf0-491f-92ba-51bae487b338
   :END:

** Read Email and News
   :PROPERTIES:
   :CLOCK_MODELINE_TOTAL: today
   :ID:       85c2e69b-6f37-4236-8896-4f7dd86047c1
   :END:

The :ID: entries are created with M-x org-id-get-create.

The following functions allow clocking in tasks by ID so the key sequence f9-m clocks in the mail task and f9-o clocks in the organization task from any emacs buffer. f9-SPC switches back to the interrupted task.

(defun bh/clock-in-task-by-id (id)
  "Clock in a task by id"
  (require 'org-id)
  (save-restriction
    (widen)
    (org-with-point-at (org-id-find id 'marker)
      (org-clock-in nil))))

(defun bh/clock-in-organization-task ()
  (interactive)
  (bh/clock-in-task-by-id "437c2cde-fbf0-491f-92ba-51bae487b338"))

(defun bh/clock-in-read-mail-and-news-task ()
  (interactive)
  (bh/clock-in-task-by-id "85c2e69b-6f37-4236-8896-4f7dd86047c1"))

(defun bh/clock-in-interrupted-task ()
  "Clock in the interrupted task if there is one"
  (interactive)
  (if (and (not org-clock-resolving-clocks-due-to-idleness)
           (marker-buffer org-clock-marker)
           (marker-buffer org-clock-interrupted-task))
      (org-with-point-at org-clock-interrupted-task
        (org-clock-in nil))
    (org-clock-out)))

When I start or continue working on a task I clock it in with C-c C-x C-i (or just I in the agenda or speed key setting). This changes the task state from TODO to STARTED and starts the clock for this task.

Default Task
[d] norang          STARTED Organization                  <-- Task B
The task interrupted by starting the last one
[i] norang          STARTED Organization                  <-- Task B
Current Clocking Task
[c] org             STARTED Document my use of org-mode   <-- Task A
Recent Tasks
[1] org             STARTED Document my use of org-mode   <-- Task A
[2] norang          STARTED Organization                  <-- Task B
...
[Z] org             DONE Fix default section links        <-- 35 clock task entries ago

In order to clock everything you need a task for everything. That's fine for planned projects but interruptions inevitably occur and you need some place to record whatever time you spend on that interruption.

To deal with this we create a new remember task to record the thing we are about to do. The workflow goes something like this:

• You are clocking some task and an interruption occurs
• Create a quick remember task C-M-r
• Type the heading
• clock it in C-c C-x C-i
• file it C-c C-c
• Go do it
• mark it DONE
• clock something else in (return to the interrupted task with C-u C-c C-x C-i i)
• refile the newly created and clocked task later

This means you can ignore the details like where this task really belongs in your org file layout and just get on with completing the thing. Refiling a bunch of tasks later in a group when it is convenient to refile the tasks saves time in the long run.

To find a task to work on I use one of the following options (generally listed most frequently used first)

• Use the clock history C-u C-c C-x C-i Go back to something I was clocking that is not finished
• Pick something off today's agenda SCHEDULED or DEADLINE items that need to be done soon
• Pick something off the STARTED tasks agenda view Work on some unfinished task to move to completion
• Use an agenda view with filtering to pick something to work on

Sometimes it is necessary to edit clock entries so they reflect reality. I find I do this for maybe 2-3 entries in a week.

Occassionally I cannot clock in a task on time because I'm away from my computer. In this case the previous clocked task is still running and counts time for both tasks which is wrong.

I make a note of the time and then when I get back to my computer I clock in the right task and edit the start and end times to correct the clock history.

To visit the clock line for an entry quickly use the agenda log mode. F12 a l shows all clock lines for today. I use this to navigate to the appropriate clock lines quickly. F11 goes to the current clocked task but the agenda log mode is better for finding and visiting older clock entries.

Use F12 a l to open the agenda in log mode and show only logged clock times. Move the cursor down to the clock line you need to edit and hit TAB and you're there.

To edit a clock entry just put the cursor on the part of the date you want to edit (use the keyboard not the mouse - since the clicking on the timestamp with the mouse goes back to the agenda for that day) and hit the S-<up arrow> or S-<down arrow> keys to change the time.

The following setting makes time editing round to 15 minute increments:

(setq org-time-stamp-rounding-minutes (quote (1 15)))

Editing the time with the shift arrow combination also updates the total for the clock line which is a nice convenience.

I always check that I haven't created task overlaps when fixing time clock entries by viewing them with log mode on in the agenda.

I want my clock entries to be as accurate as possible but editing to the exact minute (instead of rounding to 15 minutes) takes more time and isn't worth the hassle. Rounding to 15 minutes gets me close to the time I want quickly and if extra refining is needed I can edit the timestamp directly and update the total with C-c C-y.

At the beginning of the month I invoice my clients for work done last month. This is where I review my clocking data for correctness before billing for the clocked time.

Billing for clocked time basically boils down to the following steps:

1. Verify that that clock data in complete and correct
2. Use clock reports to summarize time spent
3. Create an invoice based on the clock data

   I currently create invoices in an external software package based on the org-mode clock data.

4. Archive complete tasks so they are out of the way.

   See *Archiving for more details.

;; Sometimes I change tasks I'm clocking quickly - this removes clocked tasks with 0:00 duration
(setq org-clock-out-remove-zero-time-clocks t)

;; Agenda log mode items to display (clock time only by default)
(setq org-agenda-log-mode-items (quote (clock)))

;; Agenda clock report parameters (no links, 2 levels deep)
(setq org-agenda-clockreport-parameter-plist (quote (:link nil :maxlevel 2)))

Estimating how long tasks take to complete is a difficult skill to master. Org-mode makes it easy to practice creating estimates for tasks and then clock the actual time it takes to complete.

By repeatedly estimating tasks and reviewing how your estimate relates to the actual time clocked you can tune your estimating skills.

; Set default column view headings: Task Effort Clock_Summary
(setq org-columns-default-format "%80ITEM(Task) %10Effort(Effort){:} %10CLOCKSUM")

; global Effort estimate values
(setq org-global-properties (quote (("Effort_ALL" . "0:10 0:30 1:00 2:00 3:00 4:00 5:00 6:00 7:00 8:00"))))

Original Estimate
#+BEGIN: columnview :hlines 1 :id local
| Task                        | Estimated Effort | CLOCKSUM |
|-----------------------------+------------------+----------|
| ** TODO Project to estimate |             5:40 |          |
| *** TODO Step 1             |             0:10 |          |
| *** TODO Step 2             |             0:10 |          |
| *** TODO Step 3             |             5:10 |          |
| **** TODO Step 3.1          |             2:00 |          |
| **** TODO Step 3.2          |             3:00 |          |
| **** TODO Step 3.3          |             0:10 |          |
| *** TODO Step 4             |             0:10 |          |
#+END:

Here are my tag definitions with associated keys for filtering in the agenda views.

The startgroup - endgroup (@XXX) tags are mutually exclusive - selecting one removes a similar tag already on the task. These are the context tags - you can't be in two places at once so if a task is marked with @farm and you add @office then the @farm tag is removed automagically.

The other tags QUOTE .. CANCELLED are not mutually exclusive and multiple tags can appear on a single task. Some of those tags are created by todo state change triggers. The shortcut key is used to add or remove the tag using C-c C-q or to apply the task for filtering on the agenda.

I have both FARM and @farm tags. FARM is set by a FILETAGS entry and just gives me a way to filter anything farm related. The @farm tag signifies that the task as to be done at the farm. If I have to call someone about something that would have a FARM tag but I can do that at home on my lunch break. I don't physically have to be at the farm to make the call.

; Tags with fast selection keys
(setq org-tag-alist (quote ((:startgroup)
                            ("@errand" . ?e)
                            ("@office" . ?o)
                            ("@home" . ?h)
                            ("@farm" . ?f)
                            (:endgroup)
                            ("PHONE" . ?p)
                            ("QUOTE" . ?q)
                            ("NEXT" . ?n)
                            ("WAITING" . ?w)
                            ("FARM" . ?F)
                            ("HOME" . ?H)
                            ("ORG" . ?O)
                            ("NORANG" . ?N)
                            ("crypt" . ?c)
                            ("MARK" . ?M))))

; Allow setting single tags without the menu
(setq org-fast-tag-selection-single-key (quote expert))

; For tag searches ignore tasks with scheduled and deadline dates
(setq org-agenda-tags-todo-honor-ignore-options t)

Filetags are a convenient way to apply one or more tags to all of the headings in a file.

Filetags look like this:

; Tags with fast selection keys
(setq org-tag-alist (quote ((:startgroup)
                            ("@errand" . ?e)
                            ("@office" . ?o)
                            ("@home" . ?h)
                            ("@farm" . ?f)
                            (:endgroup)
                            ("PHONE" . ?p)
                            ("QUOTE" . ?q)
                            ("NEXT" . ?n)
                            ("WAITING" . ?w)
                            ("FARM" . ?F)
                            ("HOME" . ?H)
                            ("ORG" . ?O)
                            ("NORANG" . ?N)
                            ("crypt" . ?c)
                            ("MARK" . ?M))))

; Allow setting single tags without the menu
(setq org-fast-tag-selection-single-key (quote expert))

; For tag searches ignore tasks with scheduled and deadline dates
(setq org-agenda-tags-todo-honor-ignore-options t)

I have the following #+FILETAGS: entries in my org-mode files:

The following tags are automatically added or removed by todo state triggers described previously in *ToDo state triggers

• WAITING
• CANCELLED
• NEXT

The first day of the week (usually Monday) I do my weekly review. I keep a list like this one to remind me what needs to be done.

To keep the agenda fast I set

; Tags with fast selection keys
(setq org-tag-alist (quote ((:startgroup)
                            ("@errand" . ?e)
                            ("@office" . ?o)
                            ("@home" . ?h)
                            ("@farm" . ?f)
                            (:endgroup)
                            ("PHONE" . ?p)
                            ("QUOTE" . ?q)
                            ("NEXT" . ?n)
                            ("WAITING" . ?w)
                            ("FARM" . ?F)
                            ("HOME" . ?H)
                            ("ORG" . ?O)
                            ("NORANG" . ?N)
                            ("crypt" . ?c)
                            ("MARK" . ?M))))

; Allow setting single tags without the menu
(setq org-fast-tag-selection-single-key (quote expert))

; For tag searches ignore tasks with scheduled and deadline dates
(setq org-agenda-tags-todo-honor-ignore-options t)

so only today's date is shown by default. I only need the weekly view during my weekly review and this keeps my agenda generation fast.

I have a recurring task which keeps my weekly review checklist handy. This pops up as a reminder on Monday's. This week I'm doing my weekly review on Tuesday since Monday was a holiday.

** STARTED Weekly Review [0/5]
   SCHEDULED: <2009-05-18 Mon ++1w> 
   :LOGBOOK:...
   :PROPERTIES:...

   What to review:

    - [ ] Check follow-up folder
    - [ ] Review new tasks                                  F12-r
      - if it takes less than 5 minutes just do it
      - otherwise assign an estimated time and file it somewhere
      - Refile billable work to appropriate location
    - [ ] Check for stuck projects and add next tasks       F12-#         
    - [ ] Review tasks                                      F12 t
      - [ ] Waiting tasks                                         / W
      - [ ] Next Tasks                                      F12 n
        - Move NEXT tag to subtasks or remove as required
    - [ ] Make plan for the week (out of NEXT tasks)
      - schedule important items onto the agenda
      - [ ] Review weekly plan                              F12 a w

    - start work
      - daily agenda first - knock off items
        - complete them or adjust deadline warning days appropriately
      - when agenda is empty - work on next tasks

The first item [ ] Check follow-up folder makes me pull out the paper file I dump stuff into all week long - things I need to take care of but are in no particular hurry to deal with. Stuff I get in the mail etc that I don't want to deal with now. I just toss it in my Follow-Up folder in the filing cabinet and forget about it until the weekly review.

I go through the folder and weed out anything that needs to be dealt with. After that everything else is in org-mode. I tend to schedule tasks onto the agenda for the coming week so that I don't spend lots of time trying to find what needs to be worked on next.

This works for me. You're mileage may vary ;)

Every level 2 task is a project. Projects without an explicit DEADLINE or SCHEDULED date show up in the global todo and stuck project lists.

Projects are 'stuck' if they have no NEXT task defined. I use tags to identify NEXT tasks (so the task todo state keyword is one of TODO or STARTING). Clocking in a task automatically adds NEXT keyword.

Org-mode stuck projects lists projects that have no next task defined. I normally review these in my weekly review and assign a NEXT task to all projects to clear the stuck project list. This helps to keep projects moving forwards.

(setq org-stuck-projects (quote ("LEVEL=2-REFILE-WAITING|!-DONE-CANCELLED-OPEN" nil ("NEXT") "")))

Todo state triggers (see *ToDo state triggers) automatically remove NEXT tags when tasks change to specific states.

The stuck project view is available with F12 #.

My normal archiving procedure is to move entire subtrees to a separate archive file for the project. Task subtrees in FILE.org get archived to FILE.org_archive using the a y command in the agenda.

I archive entire projects and subtrees into a single forever-growing file. My archive files are huge but so far I haven't found a need to split them by year (or decade) :)

All of my tasks to archive start at level 2 so I use an agenda custom command to list all tasks that are ready to archive. F12 A shows all tasks ready to archive and I can just run a simple macro to archive each one in turn. My normal sequence is F12 A C-n C-n to get to the first task to archive followed by a keyboard macro to archive and display the next task C-x ( a y SPC C-x ). Then I just execute the macro repeatedly with C-x e e e e, … for each subtree to archive.

I used to archive by visiting one file at a time and doing a tags match for LEVEL=2 – using the agenda does all of my files in org-agenda-files much more efficiently.

The following setting ensures that task states are untouched when they are archived. This makes it possible to archive tasks that are not marked DONE.

(setq org-archive-mark-done nil)

The only time I set the ARCHIVE tag on a task is to prevent it from opening by default because it has tons of information I don't really need to look at on a regular basis. I can open the task with C-TAB if I need to see the gory details (like a huge table of data related to the task) but normally I don't need that information displayed.

Archiving monthly works well for me. I normally invoice clients on the first of the month and after using the time clock information for the previous month I archive any DONE tasks and projects.

This keeps my main working files clutter-free. If I ever need the detail for the archived tasks they are available in the appropriate archive file.

Now I've discovered org-babel and how easy it is to generate decent graphics using ditta and graphviz.

The setup is really easy. ditaa is provided with the org-mode source. You'll have to install the graphviz package for your system.

(setq org-ditaa-jar-path "~/java/ditaa0_6b.jar")

(require 'org-babel-init)

(require 'org-babel-dot)
(require 'org-babel-ditaa)

(org-babel-load-library-of-babel)

Now you just create a begin-src block for the appropriate tool, edit the text, and build the pictures with C-c C-c. You can view the result directly in Emacs with C-c C-o anywhere in the block.

ditaa is a great tool for quickly generating graphics to convey ideas and ditaa is included with org-mode! All of the graphics in this document are automatically generated by org-mode using plain text source.

The following graphic is one example of what you can do easily with ditaa:

This

#+begin_src ditaa :file communication.png :cmdline -r -s 0.8
        +-----------+        +---------+  
        |    PLC    |        |         |                
        |  Network  +<------>+   PLC   +<---=---------+ 
        |    cRED   |        |  c707   |              | 
        +-----------+        +----+----+              | 
                                  ^                   | 
                                  |                   | 
                                  |  +----------------|-----------------+
                                  |  |                |                 |
                                  v  v                v                 v
          +----------+       +----+--+--+      +-------+---+      +-----+-----+       Windows clients
          |          |       |          |      |           |      |           |      +----+      +----+
          | Database +<----->+  Shared  +<---->+ Executive +<-=-->+ Operator  +<---->|cYEL| . . .|cYEL|
          |   c707   |       |  Memory  |      |   c707    |      | Server    |      |    |      |    |
          +--+----+--+       |{d} cGRE  |      +------+----+      |   c707    |      +----+      +----+
             ^    ^          +----------+             ^           +-------+---+
             |    |                                   |                        
             |    +--------=--------------------------+                    
             v                                                             
    +--------+--------+                                                         
    |                 |                                                         
    | Millwide System |            -------- Data ---------                      
    | cBLU            |            --=----- Signals ---=--                      
    +-----------------+                                                         
#+end_src

becomes this!

Graphviz is another great tool for creating graphics in your documents.

This

#+begin_src dot :file gv01.png :cmdline -Kdot -Tpng
digraph G {
  size="8,6"
  ratio=expand
  edge [dir=both]
  plcnet [shape=box, label="PLC Network"]
  subgraph cluster_wrapline {
    label="Wrapline Control System"
    color=purple
    subgraph {
    rank=same
    exec
    sharedmem [style=filled, fillcolor=lightgrey, shape=box]
    }
    edge[style=dotted, dir=none]
    exec -> opserver
    exec -> db
    plc -> exec
    edge [style=line, dir=both]
    exec -> sharedmem
    sharedmem -> db
    plc -> sharedmem
    sharedmem -> opserver
  }
  plcnet -> plc [constraint=false]
  millwide [shape=box, label="Millwide System"]
  db -> millwide

  subgraph cluster_opclients {
    color=blue
    label="Operator Clients"
    rankdir=LR
    labelloc=b
    node[label=client]
    client1 -> client2 -> client3 [constraint=false]
    opserver -> client1
    opserver -> client2
    opserver -> client3
  }
}
#+end_src

becomes this!

The -Kdot is optional (defaults to dot) but you can substitute other graphviz types instead here (ie. twopi, neato, circo, etc).

Org-mode exports the current file to one of the standard formats by invoking an export function. The standard key binding for this is C-c C-e followed by the key for the type of export you want.

This works great for single files or parts of files – if you narrow the buffer to only part of the org-mode file then you only get the narrowed detail in the export.

I mainly use publishing for publishing multiple files or projects. I don't want to remember where the created export file needs to move to and org-mode projects are a great solution to this.

The http://doc.norang.ca website (and a bunch of other files that are not publicly available) are all created by editing org-mode files and publishing the project the file is contained in. This is great for people like me who want to figure out the details once and forget about it. I love stuff that Just Works(tm).

I have 3 main projects I use org-mode publishing for currently:

• norang (website)
• doc.norang.ca (website)
• org files (which are selectively included by other websites)

Here's my publishing setup:

; experimenting with docbook exports - not finished
(setq org-export-docbook-xsl-fo-proc-command "fop %s %s")
(setq org-export-docbook-xslt-proc-command "xsltproc --output %s /usr/share/xml/docbook/stylesheet/nwalsh/fo/docbook.xsl %s")
;
; Inline images in HTML instead of producting links to the image
(setq org-export-html-inline-images t)
; Do not use sub or superscripts - I currently don't need this functionality in my documents
(setq org-export-with-sub-superscripts nil)
; Use org.css from the norang website for export document stylesheets
(setq org-export-html-style-extra "<link rel=\"stylesheet\" href=\"http://doc.norang.ca/org.css\" type=\"text/css\" />")
(setq org-export-html-style-include-default nil)
; Do not generate internal css formatting for HTML exports
(setq org-export-htmlize-output-type (quote css))

; List of projects
; norang - http://www.norang.ca/
; doc    - http://doc.norang.ca/
; org    - miscellaneous todo lists for publishing
(setq org-publish-project-alist
;
; http://www.norang.ca/  (norang website)
; norang-org are the org-files that generate the content
; norang-extra are images and css files that need to be included
; norang is the top-level project that gets published
      (quote (("norang-org"
               :base-directory "~/git/www.norang.ca"
               :publishing-directory "/ssh:www-data@www:~/www.norang.ca/htdocs"
               :recursive t
               :section_numbers nil
               :table-of-contents nil
               :base-extension "org"
               :publishing-function org-publish-org-to-html
               :style-include-default nil
               :section-numbers nil
               :table-of-contents nil
               :style-include-default nil
               :style "<link rel=\"stylesheet\" href=\"norang.css\" type=\"text/css\">"
               :author-info nil
               :creator-info nil)
              ("norang-extra"
               :base-directory "~/git/www.norang.ca/"
               :publishing-directory "/ssh:www-data@www:~/www.norang.ca/htdocs"
               :base-extension "css\\|pdf\\|png\\|jpg\\|gif"
               :publishing-function org-publish-attachment
               :recursive t
               :author nil)
              ("norang"
               :components ("norang-org" "norang-extra"))
;
; http://doc.norang.ca/  (norang website)
; doc-org are the org-files that generate the content
; doc-extra are images and css files that need to be included
; doc is the top-level project that gets published
              ("doc-org"
               :base-directory "~/git/doc.norang.ca/"
               :publishing-directory "/ssh:www-data@www:~/doc.norang.ca/htdocs"
               :recursive t
               :section_numbers nil
               :table-of-contents nil
               :base-extension "org"
               :publishing-function (org-publish-org-to-html org-publish-org-to-org)
               :plain-source t
               :htmlized-source t
               :style-include-default nil
               :style "<link rel=\"stylesheet\" href=\"/org.css\" type=\"text/css\">"
               :author-info nil
               :creator-info nil)
              ("doc-extra"
               :base-directory "~/git/doc.norang.ca/"
               :publishing-directory "/ssh:www-data@www:~/doc.norang.ca/htdocs"
               :base-extension "css\\|pdf\\|png\\|jpg\\|gif"
               :publishing-function org-publish-attachment
               :recursive t
               :author nil)
              ("doc"
               :components ("doc-org" "doc-extra"))
;
; Miscellaneous pages for other websites
; org are the org-files that generate the content
              ("org"
               :base-directory "~/git/org/"
               :publishing-directory "/ssh:www-data@www:~/org"
               :recursive t
               :section_numbers nil
               :table-of-contents nil
               :base-extension "org"
               :publishing-function org-publish-org-to-html
               :style-include-default nil
               :style "<link rel=\"stylesheet\" href=\"/org.css\" type=\"text/css\">"
               :author-info nil
               :creator-info nil))))

; I'm lazy and don't want to remember the name of the project to publish when I modify
; a file that is part of a project.  So this function saves the file, and publishes
; the project that includes this file
;
; It's bound to C-S-F12 so I just edit and hit C-S-F12 when I'm done and move on to the next thing
(defun bh/save-then-publish ()
  (interactive)
  (save-buffer)
  (org-save-all-org-buffers)
  (org-publish-current-project))

(global-set-key (kbd "C-s-<f12>") 'bh/save-then-publish)

The norang and doc projects publish directly into the webserver directory that serves that site. Publishing one of these projects exports all modified pages, generates images with ditaa, copies the resulting files to the webserver so that they are immediately available for viewing.

The http://doc.norang.ca/ site contains subdirectories with client documentation that are restricted access using Apache Basic authentication and I don't create links to these sites from the publicly viewable pages. http://doc.norang.ca/someclient/ would show the index for any org files under ~/git/doc.norang.ca/someclient/ if that is set up as a viewable website. I use most of the information myself but give access to clients if they are interested in the information/notes that I keep about their systems.

This works great for me - I know where my notes are and I can access them from anywhere on the internet. I'm also free to share notes with other people by simply giving them the link to the appropriate site.

All I need to remember to do is edit the appropriate org file and publish it with C-S-F12 – not exactly hard :)

; Erase all reminders and rebuilt reminders for today from the agenda
(defun bh/org-agenda-to-appt ()
  (interactive)
  (setq appt-time-msg-list nil)
  (org-agenda-to-appt))

; Rebuild the reminders everytime the agenda is displayed
(add-hook 'org-finalize-agenda-hook 'bh/org-agenda-to-appt)

; This is at the end of my .emacs - so appointments are set up when Emacs starts
(bh/org-agenda-to-appt)

; Activate appointments so we get notifications
(appt-activate t)

; If we leave Emacs running overnight - reset the appointments one minute after midnight
(run-at-time "24:01" nil 'bh/org-agenda-to-appt)

Yasnippets is cool! You type the snippet name and TAB and yasnippet expands the name with the contents of the snippet text - substituting snippet variables as appropriate.

Yasnippet comes with lots of snippets for programming languages. So far I only use 1 snippet (block) for org-mode.

I downloaded and installed the unbundled version of yasnippet so that I can edit the predefined snippets. I unpacked the yasnippet software in my ~/.emacs.d/plugins directory, renamed yasnippet0.5.10 to yasnippet and added the following setup in my .emacs:

(add-to-list 'load-path (expand-file-name "~/.emacs.d/plugins"))

(require 'yasnippet)
(yas/initialize)
(yas/load-directory "~/.emacs.d/plugins/yasnippet/snippets")

;; Make TAB the yas trigger key in the org-mode-hook and turn on flyspell mode
(add-hook 'org-mode-hook
          (lambda ()
            ;; yasnippet
            (make-variable-buffer-local 'yas/trigger-key)
            (setq yas/trigger-key [tab])
            (define-key yas/keymap [tab] 'yas/next-field-group)
            ;; flyspell mode to spell check everywhere
            (flyspell-mode 1)))

Here is the definition for the block snippet:

org-mode Yasnippet: ~/.emacs.d/plugins/yasnippet/snippets/text-mode/org-mode/block

#name : #+begin_...#+end_
# --
#+begin_$1 $2
$0
#+end_$1

I use this to create #+begin_* blocks like

• #+begin_example
• #+begin_ditaa
• #+begin_dot
• #+begin_src
• etc.

Simply type block then TAB and it replaces the block text with the snippet contents. Then type src TAB emacs-lisp TAB and your snippet block is done.

Hit C-c SingeQuote(') and insert whatever emacs-lisp code you need. While in this block you're in a mode that knows how to format and colourize emacs lisp code as you enter it which is really nice. C-c SingleQuote(') exits back to org-mode. This recognizes any emacs editing mode so all you have to do is enter the appropriate mode name for the block.

This is a great time saver.

There is more than one way to do this. Use what works for you.

(global-set-key (kbd "<f5>") 'bh/org-todo)

(defun bh/org-todo ()
  (interactive)
  (org-narrow-to-subtree)
  (org-show-todo-tree nil))

Various customizations affect how the agenda views show task details. This section shows each of the customizations I use in my workflow.

;; Always hilight the current agenda line
(add-hook 'org-agenda-mode-hook '(lambda () (hl-line-mode 1)))

;; Keep tasks with dates off the global todo lists
(setq org-agenda-todo-ignore-with-date t)

;; Remove completed deadline tasks from the agenda view
(setq org-agenda-skip-deadline-if-done t)

;; Remove completed scheduled tasks from the agenda view
(setq org-agenda-skip-scheduled-if-done t)

;; Remove completed items from search results
(setq org-agenda-skip-timestamp-if-done t)

(setq org-agenda-include-diary nil)
(setq org-agenda-diary-file "~/git/org/diary.org")

#+FILETAGS: HOME
* Appointments
  :PROPERTIES:
  :CATEGORY: Appt
  :ARCHIVE:  %s_archive::* Appointments
  :END:      
** Holidays
   :PROPERTIES:
   :Category: Holiday
   :END:
%%(org-calendar-holiday)
** Some other Appointment
   ...

;; Include agenda archive files when searching for things
(setq org-agenda-text-search-extra-files (quote (agenda-archives)))

;; Show all future entries for repeating tasks
(setq org-agenda-repeating-timestamp-show-all t)

;; Show all agenda dates - even if they are empty
(setq org-agenda-show-all-dates t)

;; Sorting order for tasks on the agenda
(setq org-agenda-sorting-strategy
      (quote ((agenda habit-down time-up priority-down effort-up category-up)
              (todo priority-down)
              (tags priority-down))))

;; Start the weekly agenda today
(setq org-agenda-start-on-weekday nil)

;; Disable display of the time grid
(setq org-agenda-time-grid
      (quote (nil "----------------"
                  (800 1000 1200 1400 1600 1800 2000))))

;; Display tags farther right
(setq org-agenda-tags-column -102)

Checklists are great for repeated tasks with lots of things that need to be done. For a long time I was manually resetting the check boxes to unchecked when marking the repeated task DONE but no more! There's a contributed org-checklist that can uncheck the boxes automagically when the task is marked done.

Add the following to your .emacs

(load "~/git/org-mode/contrib/lisp/org-checklist")

and then to use it in a task you simply set the property RESET_CHECK_BOXES to t like this

** TODO Invoicing and Archive Tasks [0/7]
   DEADLINE: <2009-07-01 Wed +1m -0d> 
   :PROPERTIES:
   :RESET_CHECK_BOXES: t
   :END:

   - [ ] Do task 1
   - [ ] Do task 2
   ...
   - [ ] Do task 7

Backups that you have to work hard at don't get gone.

I lost a bunch of data over 10 years ago due to not having a working backup solution. At the time I said I'm not going to lose any important data ever again. So far so good :)

My backups get done religiously. What does this have to do with org-mode? Not much really, other than I don't spend time doing backups – they just happen – which saves me time for other more interesting things.

My backup philosophy is to make it possible to recover your data -- not necessarily easy. It doesn't have to be easy/fast to do the recovery because I'll rarely have to recover data from the backups. Saving time for recovery doesn't make sense to me. I want the backup to be fast and painless since I do those all the time.

I set up an automated network backup over 10 years ago that is still serving me well today. All of my systems gets daily backups to a network drive. These are collected weekly and written to DVD ISO images in case my machines walk off someday.

Once a week I get an email that says 'These ISO images are ready to be burned to disk' and all I have to do is write them out. Backups take minimal effort currently and I'm really happy about that.

Since then git came into my life, so backups of git repositories that are on multiple machines is much less critical than it used to be. There is an automatic backup of everything pushed to the remote repository.

Blocked tasks are tasks that have subtasks which are not in a done todo state. Blocked tasks show up in a grayed font by default in the agenda.

To enable task blocking set the following variable:

(setq org-enforce-todo-dependencies t)

This setting prevents tasks from changing to DONE if any subtasks are still open. This works pretty well except for repeating tasks. I find I'm regularly adding TODO tasks under repeating tasks and not all of the subtasks need to be complete before the next repeat cycle.

You can override the setting temporarily by changing the task with C-u C-u C-u C-c C-t but I never remember that. I set a permanent property on the repeated tasks as follows:

* TODO New Repeating Task
  SCHEDULED: <2009-06-16 Tue +1w>
  :PROPERTIES:
  :NOBLOCKING: t
  :END:
...
** TODO Subtask

This prevents the New Repeating Task from being blocked if some of the items under it are not complete.

Occassionally I need to complete tasks in a given order. Org-mode has a property ORDERED that enforces this for subtasks.

* TODO Some Task
  :PROPERTY:
  :ORDERED: t
  :END:
** TODO Step 1
** TODO Step 2
** TODO Step 3

In this case you need to complete Step 1 before you can complete Step 2, etc. and org-mode prevents the state change to a done task until the preceding tasks are complete.

This section describes various org-mode settings I use to control how tasks are displayed while I work on my org mode files.

(setq org-hide-leading-stars nil)

(setq org-odd-levels-only nil)

(setq org-cycle-separator-lines 0)

(setq org-blank-before-new-entry (quote ((heading)
                                         (plain-list-item))))

(setq org-insert-heading-respect-content t)

(setq org-insert-heading-respect-content nil)

(setq org-reverse-note-order nil)

(setq org-show-following-heading t)
(setq org-show-hierarchy-above t)
(setq org-show-siblings nil)

(setq org-special-ctrl-a/e t)
(setq org-special-ctrl-k t)
(setq org-yank-adjusted-subtrees t)

Attachments are great for getting large amounts of data related to your project out of your org-mode files. Before attachments came along I was including huge blocks of SQL code in my org files to keep track of changes I made to project databases. This bloated my org file sizes badly.

Now I can create the data in a separate file and attach it to my project task so it's easily located again in the future.

I set up org-mode to generate unique attachment IDs with org-id-method as follows:

(setq org-id-method (quote uuidgen))

Say you want to attach a file x.sql to your current task. Create the file data in /tmp/x.sql and save it.

Attach the file with C-c C-a a and enter the filename: x.sql. This generates a unique ID for the task and adds the file in the attachment directory.

** Attachments                                                :ATTACH:
   :PROPERTIES:
   :Attachments: x.sql
   :ID:       f1d38e9a-ff70-4cc4-ab50-e8b58b2aaa7b
   :END:

The attached file is saved in data/f1/d38e9a-ff70-4cc4-ab50-e8b58b2aaa7b/. Where it goes exactly isn't important for me – as long as it is saved and retrievable easily. Org-mode copies the original file /tmp/x.sql into the appropriate attachment directory.

Tasks with attachments automatically get an ATTACH tag so you can easily find tasks with attachments with a tag search.

To open the attachment for a task use C-c C-a o. This prompts for the attachment to open and TAB completion works here.

The ID changes for every task header when a new ID is generated.

It's possible to use named directories for attachments but I haven't needed this functionality yet – it's there if you need it.

I store my org-mode attachments with my org files in a subdirectory data. These are automatically added to my git repository along with any other org-mode changes I've made.

Deadlines and due dates are a fact or life. By default I want to see deadlines in the agenda 30 days before the due date.

The following setting accomplishes this:

(setq org-deadline-warning-days 30)

This gives me plenty of time to deal with the task so that it is completed on or before the due date.

I also use deadlines for repeating tasks. If the task repeats more often than once per month it would be always bugging me on the agenda view. For these types of tasks I set an explicit deadline warning date as follows:

** TODO Pay Wages
   DEADLINE: <2009-07-01 Wed +1m -0d> 

This example repeats monthly and shows up in the agenda on the day it is due (with no prior warning). You can set any number of lead days you want on DEADLINES using -Nd where N is the number of days in advance the task should show up in the agenda. If no value is specified the default org-deadline-warning-days is used.

I generate org-mode tables with details of task specifications and record structures for some of my projects. My clients like to use spreadsheets for this type of detail.

It's easy to share the details of the org-mode table by exporting in HTML but that isn't easy for anyone else to work with if they need to edit data.

To solve this problem I export my table as comma delimited values (CSV) and then send that to the client (or read it into a spreadsheet and email the resulting spreadsheet file).

Org-mode can export tables as TAB or comma delimited formats. I set the default format to CSV with:

(setq org-table-export-default-format "orgtbl-to-csv")

Exporting to CSV format is the only one I use and this provides the default so I can just hit RETURN when prompted for the format.

To export the following table I put the cursor inside the table and hit M-x org-table-export which prompts for a filename and the format which defaults to orgtbl-to-csv from the setting above.

One	Two	Three
1	1	2
3	6	5
fred	kpe	mary
234.5	432.12	324.3

This creates the file with the following data

One,Two,Three
1,1,2
3,6,5
fred,kpe,mary
234.5,432.12,324.3

Links to emails, web pages, and other files are sprinkled all over my org files. The following setting control how org-mode handles opening the link.

(setq org-link-frame-setup (quote ((vm . vm-visit-folder-other-frame)
                                   (gnus . gnus-other-frame)
                                   (file . find-file-other-window))))

I like to keep 2 frames open for Emacs - one for org and one for Gnus. When I open a link to an email org loads the message in the other gnus frame. I find this much better than replacing the task data I'm currently looking at.

Similarly opening a file splits the window and displays the file in the other window of the current frame.

This works well for me. Your mileage may vary :)

Most of my logging is controlled by the global org-todo-keywords

My logging settings are set as follows:

(setq org-log-done (quote time))
(setq org-log-into-drawer t)

With org-todo-keywords set as

(setq org-todo-keywords (quote ((sequence "TODO(t)" "STARTED(s!)" "|" "DONE(d!/!)")
 (sequence "WAITING(w@/!)" "SOMEDAY(S!)" "OPEN(O@)" "|" "CANCELLED(c@/!)")
 (sequence "QUOTE(q!)" "QUOTED(Q!)" "|" "APPROVED(A@)" "EXPIRED(E@)" "REJECTED(R@)"))))

This adds a log entry whenever a task moves to any of the following states:

• to STARTED status
• to or out of DONE status
• to WAITING status (with a note) or out of WAITING status
• to SOMEDAY status
• to OPEN status (with a note)
• to CANCELLED status (with a note) or out of CANCELLED status
• to QUOTE status
• to QUOTED status
• to APPROVED status (with a note)
• to EXPIRED status (with a note)
• to REJECTED status (with a note)

I keep clock times and states in the LOGBOOK drawer to keep my tasks uncluttered. If a task is WAITING then the reason for why it is waiting is near the top of the LOGBOOK and unfolding the LOGBOOK drawer provides that information.

Org-mode has this great new feature for signalling alarms when the estimated time for a task is reached. I use this to limit the amount of time I spend on a task during the day.

As an example, I've been working on this document for over two months now. I want to get it finished but I can't just work on it solely until it's done because then nothing else gets done. I want to do a little bit every day but limit the total amount of time I spend documenting org-mode to an hour a day.

To this end I have a task

** STARTED Document my use of org-mode
   :LOGBOOK:...
   :PROPERTIES:
   :CLOCK_MODELINE_TOTAL: today
   :Effort:   1:00
   :END:

The task has an estimated effort of 1 hour and when I clock in the task it gives me a total in the mode-line like this

--:**  org-mode.org   91% (2348,73) Git:master  (Org Fly yas Font)-----[0:35/1:00 (Document my use of org-mode)]-------

I've spent 35 minutes of my 1 hour so far today on this document and other help on IRC.

I set up an alarm so the Star Trek red alert klaxon goes off when the total estimated time is hit. (Yes I'm a Trekkie :) )

(setq org-clock-sound "/usr/local/lib/alert1.wav")

When the one hour time limit is hit the alarm sound goes off and a message states that I should be done working on this task. If I switch tasks and try to clock in this task again I get the sound each and every time I clock in the task. This nags me to go work on something else :)

You can use similar setups for repeated tasks. By default the last repeat time is recorded as a property when a repeating task is marked done. For repeating tasks the mode-line clock total counts since the last repeat time by default. This lets you accumulate time over multiple days and counts towards your estimated effort limit.

John Wiegley recently added support for Habit tracking to org-mode.

I have lots of habits (some bad) but I'd still like to improve and build new good habits. This is what habit tracking is for. It shows a graph on the agenda of how well you have been doing on developing your habits.

I have habits like:

• Hand wash the dishes
• 30 minute brisk walk
• Clean the house

etc. and most of these need a push to get done regularly. Logging of the done state needs to be enabled for habit tracking to work.

A habit is just like a regular task except it has a special PROPERTY value setting and a special SCHEDULED date entry like this:

** TODO Update Org Mode Doc
   SCHEDULED: <2009-11-21 Sat .+7d/30d>
   [2009-11-14 Sat 11:45]
   :PROPERTIES:
   :STYLE: habit
   :END:

This marks the task as a habit and separates it from the regular task display on the agenda. When you mark a habit done it shows up on your daily agenda the next time based on the first interval in the SCHEDULED entry (.+1d)

The special SCHEDULED entry states that I want to do this every day but at least every 2 days. If I go 3 days without marking it DONE it shows up RED on the agenda indicating that I have been neglecting this habit.

The world isn't going to end if you neglect your habits. You can hide and display habits quickly using the K key on the agenda.

These are my settings for habit tracking.

; Enable habit tracking (and a bunch of other modules)
(setq org-modules (quote (org-bbdb org-bibtex org-crypt org-gnus org-id org-info org-jsinfo org-habit org-inlinetask org-irc org-mew org-mhe org-protocol org-rmail org-vm org-wl org-w3m)))
; global STYLE property values for completion
(setq org-global-properties (quote (("STYLE_ALL" . "habit"))))
; position the habit graph on the agenda to the right of the default
(setq org-habit-graph-column 50)

I tend to keep habits under a level 1 task * Habits with a special logging property that only logs changes to the DONE state. This allows me to cancel a habit and not record a timestamp for it since that messes up the habit graph. Cancelling a habit just to get it off my agenda because it's undoable (like get up before 6AM) should not mark the habit as done today. I only cancel habits that repeat every day.

My habit tasks look as follows - and I tend to have one in every org file that can have habits defined

* Habits
  :PROPERTIES:
  :LOGGING:  DONE(!)
  :ARCHIVE:  %s_archive::* Habits
  :END:

I use git to synchronize my org-mode files between my laptop and my workstation. This normally requires saving all the current changes, pushing to a bare repo, and fetching on the other system. After that I need to revert all of my org-mode files to get the updated information.

I used to use org-revert-all-org-buffers but have since discovered global-auto-revert-mode. With this setting any files that change on disk where there are no changes in the buffer automatically revert to the on-disk version.

This is perfect for synchronizing my org-mode files between systems.

(setq global-auto-revert-mode t)

I used to keep my encrypted data like account passwords in a separate GPG encrypted file. Now I keep them in my org-mode files with a special tag instead. Encrypted data is kept in the org-mode file that it is associated with.

org-crypt allows you to tag headings with a special tag crypt and org-mode can keep data in these headings encrypted when saved to disk. You decrypt the heading temporarily when you need access to the data and org-mode re-encrypts the heading as soon as you save the file.

I use the following setup for encryption:

(require 'org-crypt)
; Encrypt all entries before saving
(org-crypt-use-before-save-magic)
; Which tag is used to mark headings to be encrypted
(setq org-tags-exclude-from-inheritance (quote ("crypt")))
; GPG key to use for encryption
(setq org-crypt-key "F0B66B40")

M-x org-decrypt-entry will prompt for the passphrase associated with your encryption key and replace the encrypted data where the point is with the plaintext details for your encrypted entry. As soon as you save the file the data is re-encrypted for your key. Encrypting does not require prompting for the passphrase - that's only for looking at the plain text version of the data.

I tend to have a single encrypted entry per file (like * Passwords). I prevent the crypt tag from using inheritance so that I don't have encrypted data inside encrypted data. I found M-x org-decrypt-entries prompting for the passphrase to decrypt data over and over again (once per entry to decrypt) too inconvenient.

I leave my entries encrypted unless I have to look up data - I decrypt on demand and then save the file again to re-encrypt the data. This keeps the data in plain text as short as possible.

There's a new and exciting feature called org-speed-commands in the latest development version of org-mode.

Speed commands allow access to frequently used commands when on the beginning of a headline - similar to one-key agenda commands. Speed commands are user configurable and org-mode provides a good set of default commands.

I have the following speed commands set up in addition to the defaults. I don't use priorities so I override the default settings for the 1, 2, and 3 keys.

(setq org-use-speed-commands t)
(setq org-speed-commands-user (quote (("0" . delete-window)
                                      ("1" . delete-other-windows)
                                      ("2" . split-window-vertically)
                                      ("3" . split-window-horizontally)
                                      ("h" . hide-other)
                                      ("k" . org-kill-note-or-show-branches)
                                      ("r" . org-reveal))))

The variable org-speed-commands-default sets a lot of useful defaults for speed command keys. The default keys I use the most are I and O for clocking in and out and t to change todo state.

2009-11-07 Sat 23:24
Org protocol is a great way to create remember notes in org-mode from other applications. I use this to create tasks to review interesting web pages I visit in Firefox.

I have a special remember template set up for org-protocol to use (set up with the w key).

My org-mode setup for org-protocol is really simple. It enables org-protocol and creates a single org-protocol remember template as described in Remember Templates.

(require 'org-protocol)

The bulk of the setup is in the Firefox application so that C-M-r on a page in Firefox will trigger the org-protocol remember template with details of the page I'm currently viewing in firefox.

I set up org-protocol in firefox as described in Keybindings for Firefox.

(setq require-final-newline t)

I insert inactive timestamps when working on org-mode files.

For remember tasks the timestamp is in the remember template but for regular structure editing I want a clean outline without timestamps normally. I find this easier to work with when brainstorming and generating the outline structure for a project.

I have the following function bound to the key sequence f9 t to insert an inactive timestamp in the text on demand.

(defun bh/insert-inactive-timestamp ()
  (interactive)
  (save-excursion
    (insert "\n")
    (org-cycle)
    (org-insert-time-stamp nil t t nil nil nil)))

(global-set-key (kbd "<f9> t") 'bh/insert-inactive-timestamp)

The following setting make RET open links instead of inserting a new line. This setting is a love-hate relationship for me. When it first came out I immediately turned it off because I wanted to insert new lines in front of my links and RET would open the link instead which at the time I found extremely annoying. Now I've trained my fingers to do C-o instead for opening the line above the link. I find I'm hitting RET to visit links a lot more than opening lines before the link - so retraining my fingers was the right move for me.

(setq org-return-follows-link t)

I use the agenda to figure out what to do work on next. I don't use priorities at all. I've played with them in the past and always go back to using no priorities.

I disable the priority setting keys in org-mode using

(setq org-enable-priority-commands nil)

This was a cute idea but I find archiving entire complete subtrees better. I don't mind having a bunch of tasks marked DONE (but not archived)

Org mode can fold (cycle) plain lists. I don't use this feature.

(setq org-cycle-include-plain-lists nil)

Strike-through emphasis is just unreadable and tends to only show up when pasting data from other files into org-mode. This just removes the strike-through completely which I find a lot nicer.

(setq org-emphasis-alist (quote (("*" bold "<b>" "</b>") ("/" italic "<i>" "</i>") ("_" underline "<span style=\"text-decoration:underline;\">" "</span>") ("=" org-code "<code>" "</code>" verbatim) ("~" org-verbatim "<code>" "</code>" verbatim))))

My Emacs setup saves all org buffers at 1 minute before the hour using the following code in my .emacs

(run-at-time "00:59" 3600 'org-save-all-org-buffers)

A cron job runs at the top of the hour to commit any changes just saved by the call to org-save-all-org-buffers above. I use a script to create the commits so that I can run it on demand to easily commit all modified work when moving from one machine to another.

crontab details:

0 * * * * ~/bin/org-git-sync.sh >/dev/null

#!/bin/sh
# Add org file changes to the repository
REPOS="org doc.norang.ca www.norang.ca"

for REPO in $REPOS
do
    echo "Repository: $REPO"
    cd ~/git/$REPO
    # Remove deleted files
    git ls-files --deleted -z | xargs -0 git rm >/dev/null 2>&1
    # Add new files
    git add . >/dev/null 2>&1
    git commit -m "$(date)"
done

core
core.*
*.html
*~
.#*
\#*\#
*.txt
*.tex
*.aux
*.dvi
*.log
*.out
*.ics
*.pdf
*.xml
*.org-source
*.png
*.toc

I use git in all of my directories where editing a file should be tracked.

This means I can edit files with confidence. I'm free to change stuff and break things because it won't matter. It's easy to go back to a previous working version or to see exactly what changed since the last commit. This is great when editing configuration files (such as apache webserver, bind9 DNS configurations, etc.)

I find this extremely useful where your edits might break things and having git tracking the changes means if you break it you can just go back to the previous working version easily. This is also true for package upgrades for software where the upgrade modifies the configuration files.

I have every version of my edits in a local git repository.

So I recently acquired a Eee PC 1000 HE which now serves as my main road-warrior laptop replacing my 6 year old Toshiba Tecra S1.

I have a server on my LAN that hosts bare git repositories for all of my projects. The problem I was facing is I have to leave in 5 minutes and want to make sure I have up-to-date copies of everything I work on when I take it on the road (without Internet access).

To solve this I use a USB stick with bare git repositories on it. This includes my org-mode repositories as well as any other git repositories I'm interested in.

Just before I leave I mount my USB stick on my workstation and run usb-git-pull then usb-git-push. For any repositories that give errors due to non-fast-forward merges I manually merge as required and rerun usb-git-push until it reports no errors. This normally takes a minute to two to do. Then I grab my Eee PC and my USB stick and leave.

Later I mount my USB stick in the Eee PC and do usb-git-fetch to grab all of the commits from my workstation. I can merge as required for whatever I want to work on when I'm on the road knowing I have full up-to-date history of all my git repos on the USB stick.

This really works great! The problem I had with using a local lan bare repo was I'd forget to push/fetch a few repostories - always the ones I actually wanted to use when offline. Using the USB stick guarantees that all repositories are up to date and allows me to be completely mobile and not dependent on Internet access.

I mount my USB stick in a directory /usb using the fstab entry as follows:

/dev/sdb1 /usb vfat defaults,user,noauto,shortname=mixed 0 0

Each of my repositories has a remote usb and I push matching branches to the remote by default.

git push usb

in any repo will push all refs (branches) that already exist in the repo on the usb stick.

The 3 scripts I use do the following:

Script	Description
usb-git-fetch	For each repo on the USB stick fetch from it if it exists on this machine
usb-git-pull	For each repo on the USB stick pull into the current branch
usb-git-push	For each repo on the USB stick push to it if it exists on this machine
usb-git-missing	For each repo on the USB stick report if we don't have a local copy of it

Lately I've been using usb-git-pull and usb-git-push only. If anything goes wrong the script stops so I can fix whatever made the pull or push operation fail. Then I just rerun the script until it runs to completion.

Here is the usb-git-fetch script

#!/bin/sh
find /usb -type d -name '*.git' | sed 's@^/usb/@@; s/.git$//' | while read repo; do 
  if test -d ~/${repo/.git}
  then
    echo REPO: $repo
    cd ~/$repo
    git fetch usb
  fi
done

Here is the usb-git-pull script

#!/bin/sh
if find /usb -type d -name '*.git' | sed 's@^/usb/@@; s/.git$//' | while read repo; do
      if test -d ~/${repo/.git}
      then
        echo REPO: $repo
        cd ~/$repo 
        if ! git pull usb
        then
          exit 1
        fi
      fi
    done
then
    echo Unmounting USB stick...
    umount /usb
    echo All done.
else
    echo Fix and redo.
fi

Here is the usb-git-push script

#!/bin/sh
if find /usb -type d -name '*.git' | sed 's@^/usb/@@; s/.git$//' | while read repo; do
      if test -d ~/${repo/.git}
      then
        echo REPO: $repo
        cd ~/$repo
        if ! git push usb
        then
          exit 1
        fi
      fi
    done
then
    echo Unmounting USB stick...
    umount /usb
    echo All done.
else
    echo Fix and redo.
fi

Here is the usb-git-missing script

#!/bin/sh
find /usb -type d -name '*.git' | sed 's@^/usb/@@; s/.git$//' | while read repo; do 
  if ! test -d ~/${repo/.git}
  then
    echo REPO: $repo
  fi
done