#+TITLE: Org Mode - Organize Your Life In Plain Text! #+LANGUAGE: en #+AUTHOR: Bernt Hansen (IRC:Thumper_ on freenode) #+EMAIL: bernt@norang.ca #+OPTIONS: H:3 num:t toc:2 \n:nil @:t ::t |:t ^:nil -:t f:t *:t <:t #+OPTIONS: TeX:t LaTeX:nil skip:nil d:nil todo:t pri:nil tags:not-in-toc #+OPTIONS: author:t creator:t timestamp:t #+DESCRIPTION: A description of how I currently use org-mode #+KEYWORDS: org-mode Emacs organization GTD getting-things-done git #+SEQ_TODO: UNFINISHED COMPLETE #+INFOJS_OPT: view:nil toc:t ltoc:t mouse:underline buttons:0 path:http://orgmode.org/org-info.js #+EXPORT_SELECT_TAGS: export #+EXPORT_EXCLUDE_TAGS: noexport #+LINK_UP: #+LINK_HOME: * Overview Org-mode is a fabulous organizational tool built by Carsten Dominik that operates on plain text files. Org-mode is part of Emacs. This document assumes you've had some exposure to org-mode already so concepts like the agenda, remember mode, etc. won't be completely foreign to you. More information about org-mode can be found in the [[http://orgmode.org/index.html#sec-4.1][Org-Mode Manual]] and on the [[http://orgmode.org/worg/][Worg Site]]. I have been using org-mode as my personal information manager for years now. I started small with just the default =TODO= and =DONE= keywords. I added small changes to my workflow and over time it evolved into what is described by this document. I still change my workflow and try new things regularly. This document describes mature workflows in my current org-mode setup. I tend to document changes to my workflow 30 days after implementing them (assuming they are still around at that point) so that the new workflow has a chance to mature. History of changes to this document can be found [[http://git.norang.ca/?p=org-mode-doc.git;a=summary][here]]. This document is created using the publishing features of org-mode. The source for this document can be found as [[http://doc.norang.ca/org-mode.org.html][colorized HTML]] and [[http://doc.norang.ca/org-mode.org][plain text org file]]. Some of the customized Emacs settings described in this document are set at their default values. This explicitly shows the setting for important org-mode variables used in my workflow and to keep my workflow behaviour stable in the event that the default value changes in the future. * Getting Started I use =org-mode= in most of my emacs buffers. ** Org-Mode Setup :PROPERTIES: :CUSTOM_ID: Setup :END: 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. #+begin_src emacs-lisp ;;; ;;; 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) #+end_src =orgstruct++-mode= is enabled in =Gnus= message buffers to aid in creating structured email messages. #+begin_src emacs-lisp (setq message-mode-hook (quote (orgstruct++-mode (lambda nil (setq fill-column 72) (flyspell-mode 1)) turn-on-auto-fill bbdb-define-all-aliases))) #+end_src =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. #+begin_src emacs-lisp ;; 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))) #+end_src ** Organizing Your Life Into Org Files 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. ** Agenda Setup 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. #+begin_src emacs-lisp (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"))) #+end_src =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. ** Org file structure 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. ** Key bindings 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). #+end_example | 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 | | 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 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: #+begin_src emacs-lisp ;; Custom Key Bindings (global-set-key (kbd "") 'org-agenda) (global-set-key (kbd "") 'bh/org-todo) (global-set-key (kbd "") 'widen) (global-set-key (kbd "") 'set-truncate-lines) (global-set-key (kbd "") 'org-cycle-agenda-files) (global-set-key (kbd " b") 'bbdb) (global-set-key (kbd " c") 'calendar) (global-set-key (kbd " f") 'boxquote-insert-file) (global-set-key (kbd " g") 'gnus) (global-set-key (kbd " h") 'hide-other) (global-set-key (kbd " i") (lambda () (interactive) (info "~/git/org-mode/doc/org.info"))) (global-set-key (kbd " r") 'boxquote-region) (global-set-key (kbd " t") 'bh/insert-inactive-timestamp) (global-set-key (kbd " u") (lambda () (interactive) (untabify (point-min) (point-max)))) (global-set-key (kbd " v") 'visible-mode) (global-set-key (kbd "C-") 'previous-buffer) (global-set-key (kbd "C-x n r") 'narrow-to-region) (global-set-key (kbd "C-") 'next-buffer) (global-set-key (kbd "") 'org-clock-goto) (global-set-key (kbd "C-") 'org-clock-in) (global-set-key (kbd "C-s-") 'bh/save-then-publish) (global-set-key (kbd "M-") 'org-resolve-clocks) (global-set-key (kbd "C-M-r") 'org-remember) #+end_src 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. * Tasks and States I use one set of TODO keywords for all of my org files. Org-mode lets you define TODO keywords per file but I find it's easier to have a standard set of TODO keywords globally so I can use the same setup in any org file I'm working with. The only exception to this is this document :) since I don't want =org-mode= hiding the =TODO= keyword when it appears in headlines. I've set up a dummy =#+SEQ_TODO: FIXME FIXED= entry at the top of this file just to leave my =TODO= keyword untouched in this document. ** ToDo keywords Here are my =TODO= state keywords and colour settings: #+begin_src emacs-lisp (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)))) #+end_src *** Normal Task States Normal tasks go through the sequence =TODO= -> =STARTED= -> =DONE=. The second sequence is really just a convenient collection of odd-ball states for tasks (=WAITING=, =SOMEDAY=, =CANCELLED=). The following diagram shows the possible state transitions for a task. #+begin_ditaa task_states.png -r -s 0.8 : +--------+ +---------+ +--------+ : | | | | | | : +--+ TODO +------>+ STARTED +------>+ DONE | : | | cRED | | cBLU | | cGRE | : | +--+-+---+ +--+---+--+ +--------+ : | ^ ^ ^ | : | | | | | : | | : +------=----+ +------=------+ : | : +--|----=-------+ | : | | | | | : | v v v v : | +--+----+-+ +----+----+ +-----+-----+ : | | | | | | | : | | WAITING | | SOMEDAY | | CANCELLED | : | | cF60 | | cC0C | | cGRE | : | +----+----+ +---+--+--+ +-----+--+--+ : | ^ ^ | ^ ^ : | | | | | | : | +--=-----------+ +-=------------+ | : | | : +---=---------------------------------------+ : : : -------- Normal state changes : ----=--- Optional state changes #+end_ditaa *** Quotation Task States I also do fixed-price quotation work. Quotations use the following state transitions: #+begin_ditaa quote_states.png -r -s 0.8 : +----------+ : | | : +-->+ EXPIRED | : | | cGRE | : | +----------+ : | : | : +-------------+ +--------+ : +----------+ : | | | +---+ | | : | QUOTE +------>+ QUOTED +------>+ APPROVED | : | cRED | | cC0C +---+ | cGRE | : +-------------+ +--+---+-+ : +----------+ : | : | : | +----------+ : | | | : +-->+ REJECTED | : | cGRE | : +----------+ #+end_ditaa *** Purchase Order Task States Fixed price jobs normally have a =Purchase Order= associated with it which is used for billing the client. The following states track purchase orders. #+begin_ditaa po_states.png -r -s 0.8 : +----------+ +---------+ : | | | | : | OPEN +------>+ DONE | : | cRED | | cGRE | : +----------+ +---------+ #+end_ditaa *** Project Task States Every level 2 task is a project. This has several advantages over keeping an explicit project task: - It simplifies my weekly review process - Every task is considered a project so stuck project tasks stand out automatically - There are fewer states to keep track of - Clocking in the top level project task works I can clock in the top level task which changes it to =STARTED= without losing project context for the task. - Tasks with no children can be marked unstuck by simply giving them a =NEXT= tag ** Fast Todo Selection 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! #+begin_src emacs-lisp (setq org-use-fast-todo-selection t) #+end_src lisp 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 #+begin_src emacs-lisp (setq org-treat-S-cursor-todo-selection-as-state-change nil) #+end_src 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. ** ToDo state triggers 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. #+begin_src emacs-lisp (setq org-todo-state-tags-triggers (quote (("CANCELLED" ("CANCELLED" . t)) ("WAITING" ("WAITING" . t) ("NEXT")) ("SOMEDAY" ("WAITING" . t)) (done ("NEXT") ("WAITING")) ("TODO" ("WAITING") ("CANCELLED") ("NEXT")) ("DONE" ("WAITING") ("CANCELLED") ("NEXT"))) #+end_src *** Using =STARTED= for clocked tasks Tasks automatically change to =STARTED= whenever they are clocked in. #+begin_src emacs-lisp ;; Change task state to STARTED when clocking in (setq org-clock-in-switch-to-state "STARTED") #+end_src * Adding New Tasks Quickly with Remember :PROPERTIES: :CUSTOM_ID: Remember :END: To add new tasks efficiently I use a minimal number of remember templates. I used to have lots of remember templates, one for each org-file. I'd start org-remember with C-M-r and then pick a template that filed the task under =* Tasks= in the appropriate file. I found I still needed to refile these remember tasks again to the correct location within the org-file so all of these different remember templates weren't really helping at all. Since then I've changed my workflow to use a minimal number of remember templates -- I create the new task quickly and refile it once. This also saves me from maintaining my org-remember templates when I add a new org file. ** Remember Templates :PROPERTIES: :ID: 9507648b-dbfc-4ba1-96c2-36e8ba15cbd0 :END: 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 #+begin_src emacs-lisp (setq org-default-notes-file "~/git/org/refile.org") ;;; Load Org Remember Stuff (require 'remember) (org-remember-insinuate) ;; Start clock if a remember buffer includes :CLOCK-IN: (add-hook 'remember-mode-hook 'bh/start-clock-if-needed 'append) (defun bh/start-clock-if-needed () (save-excursion (goto-char (point-min)) (when (re-search-forward " *:CLOCK-IN: *" nil t) (replace-match "") (org-clock-in)))) ;; 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 :CLOCK-IN:\n %?" nil bottom nil) ("appointment" ?a "* %?\n %U" "~/git/org/todo.org" "Appointments" nil) ("org-protocol" ?w "* TODO Review %c%! :NEXT:\n %U\n :PROPERTIES:\n :Effort: 0:10\n :END:" nil bottom nil)))) #+end_src ** Separate file for Remember Tasks 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 #+begin_src org #+FILETAGS: REFILE #+end_src ** Remember Tasks is all about begin FAST 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. * Refiling Tasks :PROPERTIES: :CUSTOM_ID: Refiling :END: Refiling tasks is easy. After collecting a bunch of new tasks in my refile.org file using remember mode I need to move these to the correct org file and topic. All of my active org-files are in my =org-agenda-files= variable and contribute to the agenda. I collect remember tasks in refile.org for up to a week. I do my weekly review every Monday and one of the tasks for that is to refile all remember tasks. Often I end up refiling tasks the same day I create them because they show up in my daily clock report summary and are obviously in the wrong place. ** Refile Setup 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: #+begin_src emacs-lisp ; 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) #+end_src 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! ** Refiling Tasks 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. ** Refiling Notes 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. ** Refiling Phone Calls 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. * Custom agenda views I have 7 custom agenda views defined. Most of my old custom agenda views were rendered obsolete when filtering functionality was added to the agenda in newer versions of =org-mode=. Custom agenda views are used for: 1. Finding =STARTED= tasks 2. Finding tasks waiting on something 3. Finding tasks to be refiled 4. Finding notes 5. Finding =NEXT= tasks to work on 6. Finding projects 7. Findings tasks to be archived ** Setup #+begin_src emacs-lisp (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)))))) #+end_src 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 ** What do I work on next? 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 *** Why keep it all on the =STARTED= list? I used to have a special keyword =ONGOING= for things that I do a lot and want to clock but never really start/end. I had a special agenda view for =ONGOING= tasks that I would pull up to easily find the thing I want to clock. Since then I've moved away from using the =ONGOING= todo keyword and just use =STARTED= the same way. If a task is clocked-in it automatically moves to the =STARTED= todo state and shows up on the list without having to think about it. Having an agenda view that shows =STARTED= tasks makes it easy to pick the thing to clock - and I don't have to remember if I need to look in the =ONGOING= list or the =STARTED= list when looking for the task to clock-in. The =STARTED= list is basically 'what is current' - stuff I worked on recently and need to continue working on. I want to find the thing to work on as fast as I can and actually do work on it - not spend time hunting through my org files for the task that needs to be clocked-in. It is just easier to have it all in one short list. My =STARTED= list has less than 20 entries so it's pretty easy to find what I want. The whole point of the =STARTED= list is to make it quick and easy to find the task to clock-in. I only have 2 tasks that are permanently in a =STARTED= state. These are: - Organization - Email, News, and IRC Everything else will eventually move to a =DONE= state and fall off the list. To drop a task off the =STARTED= simply move it back to the =TODO= state. ** Reading email, newsgroups, and conversations on IRC 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 ' 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 ' 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. ** Filtering 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. *** Automatically removing context based tasks with / RET =/ RET= in the agenda is really useful. This awesome feature was added to org-mode by John Wiegley. It removes tasks automatically by filtering based on a user-provided function. I work from home and set up my day as follows: - On weekdays 8am-12am, 1pm-5pm I'm working (@office) - My son (Mark) is available on weekdays before school 8am-9am and after school to bedtime 4pm-8pm (MARK), and weekends 10am-8pm - Home tasks are done outside working hours (@home) I have the following setup to allow =/ RET= to filter tasks based on what the computer determines my current context to be at the time I run the =/ RET= filter command. #+begin_src emacs-lisp (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) #+end_src This lets me filter tasks with just =/ RET= on the agenda which removes tasks I'm not supposed to be working on now from the list of returned results. This helps to keep my agenda clutter-free. ** Keeping the =STARTED= task list under control 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=. * Time Clocking :PROPERTIES: :CUSTOM_ID: Clocking :END: Okay, I admit it. I'm a clocking fanatic. I clock everything (well almost everything). Org-mode makes this really easy. I'd rather clock too much stuff than not enough so I find it's easier to get in the habit of clocking everything. As an example of what I mean my clock data for April 20, 2009 shows 14 hours 19 minutes of clocked time (which included 3 hours and 17 minutes of painting my basement.) My clocked day started at 6:57AM and ended at 23:11PM. I have only a few holes in my clocked day (where I wasn't clocking anything): | Missing Clock Data | |--------------------| | 16:14-16:53 | | 16:55-17:19 | | 18:00-18:52 | This makes it possible to look back at the day and see where I'm spending too much time, or not enough time on specific projects. Without clocking data it's hard to tell what you did after the fact. ** Clock Setup 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: #+begin_src emacs-lisp ;; ;; Resume clocking tasks when emacs is restarted (org-clock-persistence-insinuate) ;; ;; Yes it's long... but more is better ;) (setq org-clock-history-length 35) ;; 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)) #+end_src ** Clocking in 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). This changes the task state to =STARTED= and starts the clock for this task. *** Setting a default clock task I have a default =* Organization= task in my norang.org file that I tend to put miscellaneous clock time on. While reorganizing my org-files and doing other planning work that isn't for a specific project I'll clock in this task while I do things. By clocking this task in with a double prefix =C-u C-u C-c C-x C-i= it starts the clock and makes this the default clock task. You can quickly clock in the default task with =C-u C-c C-x C-i d= *** Using the clock history to clock in old tasks You can use the clock history to restart clocks on old tasks you've clocked or to jump directly to a task you have clocked previously. I use this mainly to clock in whatever got interrupted by something. Consider the following scenario: - You are working on and clocking =Task A= (Organization) - You get interrupted and switch to =Task B= (Document my use of org-mode) - You complete =Task B= (Document my use of org-mode) - Now you want to go back to =Task A= (Organization) again to continue This is easy to deal with. 1. Clock in =Task A=, work on it 2. Go to =Task B= (or create a new task) and clock it in 3. When you are finished with =Task B= hit =C-u C-c C-x C-i i= This displays a clock history selection window like the following and selects the interrupted =[i]= entry. *Clock history selection buffer for C-u C-c C-x C-i* #+begin_example 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 #+end_example ** Clock Everything - Create New Tasks 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. ** Finding tasks to clock in 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 ** Editing clock entries 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-= or =S-= keys to change the time. The following setting makes time editing round to 15 minute increments: #+begin_src emacs-lisp (setq org-time-stamp-rounding-minutes (quote (1 15))) #+end_src lisp 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. * Time reporting and tracking ** Billing clients based on clocked time 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. *** Verify that clock data in complete and correct Since I change tasks often (sometimes more than once in a minute) I use the following setting to remove clock entries with a zero duration. #+begin_src emacs-lisp ;; 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) #+end_src This setting just keeps my clocked log entries clean - only keeping clock entries that contribute to the clock report. Before invoicing for clocked time it is important to make sure your clocked time data is correct. If you have a clocked time with an entry that is not closed (ie. it has no end time) then that is a hole in your clocked day and it gets counted as zero (0) for time spent on the task when generating clock reports. Counting it as zero is almost certainly wrong. To check for unclosed clock times I use the agenda-view log-mode (=l= in the agenda) with the following setup which shows clocked times only by default. (To see all task state changes you can issue a prefix to this command (=C-u l= in the agenda)). To check the last month's clock data I use =F12 a m left-arrow l= which shows a full month in the agenda, moves to the previous month, and shows the clocked times only. The clocked-time only display in the agenda makes it easy to quickly scan down the list to see if an entry is missing an end time. If an entry is not closed you can manually fix the clock entry based on other clock info around that time. Use the following setup to get log mode in the agenda to only show clocked times: #+begin_src emacs-lisp ;; Agenda log mode items to display (clock time only by default) (setq org-agenda-log-mode-items (quote (clock))) #+end_src *** Using clock reports to summarize time spent Billable time for clients are kept in separate org files. To get a report of time spent on tasks for =XYZ.org= you simply visit the =XYZ.org= file and run an agenda clock report for the last month with =F12 1 a m left-arrow R=. This limits the agenda to this one file, shows the agenda for a full month, moves to last month, and generates a clock report. Just scroll down to the end of the agenda to see the report. I export the agenda to a text file with =C-x C-w XYZ.txt= so I can cut and paste the report and save it as supporting information with the invoice. My agenda org clock report settings show 2 levels of detail and do not show links so that they are easier to cut and paste into other applications. #+begin_src emacs-lisp ;; Agenda clock report parameters (no links, 2 levels deep) (setq org-agenda-clockreport-parameter-plist (quote (:link nil :maxlevel 2))) #+end_src I used to have a monthly clock report dynamic block in each project org file and manually updated them at the end of my billing cycle. I moved to using agenda clock reports shortly after that feature was added since I find this much more convenient. The data isn't normally for consumption by anyone else so the format of the agenda clock report format is great for my use-case. ** Task Estimates and column view :PROPERTIES: :CUSTOM_ID: TaskEstimates :END: 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. *** Creating a task estimate with column mode I use =properties= and =column view= to do project estimates. I set up column view globally with the following headlines #+begin_src emacs-lisp ; Set default column view headings: Task Effort Clock_Summary (setq org-columns-default-format "%80ITEM(Task) %10Effort(Effort){:} %10CLOCKSUM") #+end_src This makes column view show estimated task effort and clocked times side-by-side which is great for reviewing your project estimates. A property called =Effort= records the estimated amount of time a given task will take to complete. The estimate times I use are one of: - 10 minutes - 30 minutes - 1 hour - 2 hours - 3 hours - 4 hours - 5 hours - 6 hours - 7 hours - 8 hours These are stored for easy use in =column mode= in the global property =Effort_ALL=. #+begin_src emacs-lisp ; 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")))) #+end_src To create an estimate for a task or subtree start column mode with =C-c C-x C-c= and collapse the tree with =c=. This shows a table overlayed on top of the headlines with the task name, effort estimate, and clocked time in columns. With the cursor in the =Effort= column for a task you can easily set the estimated effort value with the quick keys =1= through =9=. After setting the effort values exit =column mode= with =q=. *** Saving your estimate :PROPERTIES: :CUSTOM_ID: SavingEstimate :END: For fixed price jobs where you provide your estimate to a client, then work to complete the project it is useful to save the original estimate that is provided to the client. Save your original estimate by creating a dynamic clock report table at the top of your estimated project subtree. Entering =C-c C-x i RET= inserts a clock table report with your estimated values and any clocked time to date. #+begin_src org 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: #+end_src I normally delete the =#+BEGIN:= and =#+END:= lines from the original table after providing the estimate to the client to ensure I don't accidentally update the table by hitting =C-c C-c= on the =#+BEGIN:= line. Saving the original estimate data makes it possible to refine the project tasks into subtasks as you work on the project without losing the original estimate data. *** Reviewing your estimate =Column view= is great for reviewing your estimate. This shows your estimated time value and the total clock time for the project side-by-side. Creating a dynamic clock table with =C-c C-x i RET= is a great way to save this project review if you need to make it available to other applications. =C-c C-x C-d= also provides a quick summary of clocked time for the current org file. * Tags Tasks can have any number of arbitrary tags. Tags are used for: - filtering todo lists and agenda views - providing context to some tasks - tagging notes - tagging phone calls - tagging tasks to be refiled - tagging NEXT actions for project tasks - tagging tasks in a WAITING state because a parent task is WAITING - preventing export of some subtrees when publishing Tags are mostly used for filtering in the agenda. This means you can find tasks with a specific tag easily across your large number of org-mode files. Some tags are mutually exclusive. These are defined in a group so that only one of the tags can be applied to a task at a time (disregarding tag inheritance). I use these types for tags for applying context to a task. (Work tasks have an =@office= tag, and are done at the office, Farm tasks have an =@farm= tag and are done at the farm -- I can't change the oil on the tractor if I'm not at the farm... so I hide these and other tasks by filtering my agenda view to only =@office= tasks when I'm at the office.) Tasks are grouped together in org-files and a =#+FILETAGS:= entry applies a tag to all tasks in the file. I use this to apply the =@office= tag to projects that are Work related. ** Tags 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. #+begin_src emacs-lisp ; 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) #+end_src ** Filetags Filetags are a convenient way to apply one or more tags to all of the headings in a file. Filetags look like this: #+begin_src org #+FILETAGS: NORANG @office #+end_src I have the following =#+FILETAGS:= entries in my org-mode files: *** Non-work related org-mode files | File | Tags | |--------------+--------------| | todo.org | HOME | | gsoc2009.org | GSOC HOME | | bzflag.org | BZFLAG @home | | git.org | GIT | | org.org | ORG | | mark.org | MARK | | farm.org | FARM | *** Work related org-mode files | File | Tags | |-------------+-----------------| | norang.org | NORANG @office | | ABC.org | ABC @office | | XYZ.org | XYZ @office | | ABC-DEF.org | ABC DEF @office | | ABC-KKK.org | ABC KKK @office | | YYY.org | YYY @office | *** Refile tasks | File | Tags | |------------+--------------| | refile.org | REFILE | |------------+--------------| ** Trigger Tags The following tags are automatically added or removed by todo state triggers described previously in [[*ToDo%20state%20triggers][*ToDo state triggers]] - =WAITING= - =CANCELLED= - =NEXT= * Handling Notes Notes are little gems of knowledge that you come across during your day. They are just like tasks except there is nothing to do (except learn and memorize the gem of knowledge). Unfortunately there are way too many gems to remember and my head explodes just thinking about it. org-mode to the rescue! Often I'll find some cool feature or thing I want to remember while reading the org-mode and git mailing lists in Gnus. To create a note I use my note remember template =C-M-r n=, type a heading for the note and =C-c C-c= to save it. The only other thing to do is to refile it (later) to the appropriate project file. I have an agenda view just to find notes. Notes are refiled to an appropriate project file and task. If there is no specific task it belongs to it goes to the catchall =* Notes= task. I generally have a catchall notes task in every project file. Notes are created with a =NOTE= tag already applied by the remember template so I'm free to refile the note anywhere. As long as the note is in a project file that contributes to my agenda (ie. in org-agenda-files) then I can find the note back easily with my notes agenda view by hitting the key combination =F12 n=. I'm free to limit the agenda view of notes using standard agenda tag filtering. technical details without the need to actually remember anything - Short notes with a meaningful headline are a great way to remember other than how to find them back when you need them using =F12 n=. Notes that are project related and not generally useful can be archived with the project and removed from the agenda when the project is removed. So my org notes go in org.org and my git notes go in git.org both under the =* Notes= task. I'll forever be able to find those. A note about some work project detail I want to remember with the project is filed to the project task under the appropriate work org-mode file and eventually gets removed from the agenda when the project is complete and archived. * GTD stuff Most of my day is deadline/schedule driven. I work off of the agenda first and then pick items from the todo lists as outlined in [[*What%20do%20I%20work%20on%20next][*What do I work on next]] ** Weekly Review Process 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 #+begin_src elisp (setq org-agenda-ndays 1) #+end_src 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 ;) ** Project definition and finding stuck projects 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. #+begin_src emacs-lisp (setq org-stuck-projects (quote ("LEVEL=2-REFILE-WAITING|LEVEL=1+REFILE/!-DONE-CANCELLED-OPEN" nil ("NEXT") ""))) #+end_src Todo state triggers (see [[*ToDo%20state%20triggers][*ToDo state triggers]]) automatically remove =NEXT= tags when tasks change to specific states. The stuck project view is available with =F12 #=. * Archiving ** Archiving Subtrees 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. #+begin_src emacs-lisp (setq org-archive-mark-done nil) #+end_src ** Archive Tag - Hiding Information 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. ** When to Archive 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. * Publishing :PROPERTIES: :CUSTOM_ID: Publishing :END: I don't do a lot of publishing for other people but I do keep a set of private client system documentation online. Most of this documentation is a collection of notes exported to HTML. Almost everything at http://doc.norang.ca/ is generated by publishing org-files. The notable exception to that is the index page which is currently automatically generated from a Python script based on the HTML files that exist in the document directory. It is supposed to be possible to generate index files from org-mode but I've never spent the time to figure that out since I already have a working index page in place. Org-mode can export to a variety of publishing formats including (but not limited to) - ASCII (plain text - but not the original org-mode file) - HTML - LaTeX - Docbook which enables getting to lots of other formats like ODF, XML, etc - PDF via LaTeX or Docbook - iCal I haven't begun the scratch the surface of what org-mode is capable of doing. My main use case for org-mode publishing is just to create HTML documents for viewing online conveniently. Someday I'll get time to try out the other formats when I need them for something. ** Playing with ditaa [[http://ditaa.sourceforge.net/][ditaa]] is a great tool for quickly generating graphics to convey ideas and =ditaa= is included with org-mode! Some of the graphics in this document are automatically generated by org-mode and ditaa from plain text source. The following graphic is one example of what you can do easily with ditaa: This : #+begin_ditaa communication.png -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_ditaa becomes this! #+begin_ditaa communication.png -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_ditaa #+begin_src emacs-lisp (setq org-ditaa-jar-path "~/java/ditaa0_6b.jar") #+end_src ** Playing with graphviz [[http://www.graphviz.org/][Graphviz]] is another great tool for creating graphics in your documents. This : #+begin_dot gv01.png -Kdot -Tpng : digraph G { : concentrate=true : subgraph cluster_wrapline { : label="Wrapline Control System" : color=purple : sharedmem [style=filled, fillcolor=lightgrey, shape=box] : sharedmem -> exec [style=dotted] : sharedmem -> db [style=dotted] : sharedmem -> plc [style=dotted] : sharedmem -> opserver [style=dotted] : exec -> db : exec -> opserver : plc -> exec : } : plcnet [shape=box, label="PLC Network"] : plcnet -> plc : millwide [shape=box, label="Millwide System"] : db -> millwide : : subgraph cluster_opclients { : color=blue : client1[label="client"] : client2[label="client"] : client3[label="client"] : clientn[label="client"] : opserver -> client1 : opserver -> client2 : opserver -> client3 : opserver -> clientn : } : } : #+end_dot becomes this! #+begin_dot gv01.png -Kdot -Tpng digraph G { concentrate=true subgraph cluster_wrapline { label="Wrapline Control System" color=purple sharedmem [style=filled, fillcolor=lightgrey, shape=box] sharedmem -> exec [style=dotted] sharedmem -> db [style=dotted] sharedmem -> plc [style=dotted] sharedmem -> opserver [style=dotted] exec -> db exec -> opserver plc -> exec } plcnet [shape=box, label="PLC Network"] plcnet -> plc millwide [shape=box, label="Millwide System"] db -> millwide subgraph cluster_opclients { color=blue client1[label="client"] client2[label="client"] client3[label="client"] clientn[label="client"] opserver -> client1 opserver -> client2 opserver -> client3 opserver -> clientn } } #+end_dot The =-Kdot= is optional (defaults to =dot=) but you can substitute other graphviz types instead here (ie. =twopi=, =neato=, =circo=, etc). ** Publishing Single Files 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. ** Publishing Projects :PROPERTIES: :CUSTOM_ID: PublishingProjects :END: 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: #+begin_src emacs-lisp ; 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) ; 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 "" :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 "" :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 "" :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-") 'bh/save-then-publish) #+end_src 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 :) * Reminders :PROPERTIES: :CUSTOM_ID: Reminders :END: I use appt for reminders. It's simple and unobtrusive -- putting pending appointments in the status bar and beeping as 12, 9, 6, 3, and 0 minutes before the appointment is due. Everytime the agenda is displayed (and that's lots for me) the appointment list is erased and rebuilt from the current agenda details for today. This means everytime I reschedule something, add or remove tasks that are time related the appointment list is automatically updated the next time I look at the agenda. ** Reminder Setup #+begin_src emacs-lisp ; 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) #+end_src * Productivity Tools :PROPERTIES: :CUSTOM_ID: ProductivityTools :NOBLOCKING: t :END: This section is a miscellaneous collection of Emacs customizations that I use with org-mode so that it Works-For-Me(tm). ** Yasnippets :PROPERTIES: :CUSTOM_ID: Yasnippets :END: [[http://code.google.com/p/yasnippet/][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=: #+begin_src emacs-lisp (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))) #+end_src Here is the definition for the =block= snippet: org-mode Yasnippet: ~/.emacs.d/plugins/yasnippet/snippets/text-mode/org-mode/block #+begin_example #name : #+begin_...#+end_ # -- #+begin_$1 $2 $0 #+end_$1 #+end_example 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. ** Limit your view to what you are working on :PROPERTIES: :CUSTOM_ID: LimitingAgendaView :END: There is more than one way to do this. Use what works for you. *** Narrowing to a subtree with =bh/org-todo= =f5= is bound the function =bh/org-todo= which is defined as follows: #+begin_src emacs-lisp (global-set-key (kbd "") 'bh/org-todo) (defun bh/org-todo () (interactive) (org-narrow-to-subtree) (org-show-todo-tree nil)) #+end_src This makes it easy to hide all of the other details in your org-file temporarily by limiting your view to this task subtree. Tasks are folded and hilighted so that only tasks which are incomplete are shown. I hit =f5= a lot. This basically does a =org-narrow-to-subtree= and =C-c C-v= combination leaving the buffer in a narrowed state. I use =S-f5= to widen back to the normal view. *** Limiting the agenda to a subtree =C-c C-x <= turns on the agenda restriction lock for the current subtree. This keeps your agenda focused on only this subtree. Alarms and notifications are still active outside the agenda restriction. =C-c C-x >= turns off the agenda restriction lock returning your agenda view back to normal. I don't normally use the agenda restriction lock. I normally want to see all =work= tasks which are in multiple files so agenda view filtering works better for me. *** Limiting the agenda to a file You can limit the agenda view to a single file in multiple ways. You can use the agenda restriction lock =C-c C-x <= on the any line before the first heading to set the agenda restriction lock to this file only. This lock stays in effect until you remove it with =C-c C-x >=. Another way is to invoke the agenda with =F12 1 a= while visiting an org-mode file. This limits the agenda view to just this file. I occassionally use this to view a file not in my =org-agenda-files= in the agenda. ** Tuning the Agenda Views Various customizations affect how the agenda views show task details. This section shows each of the customizations I use in my workflow. *** Highlight the current agenda line The following code in my =.emacs= file keeps the current agenda line highlighted. This makes it obvious what task will be affected by commands issued in the agenda. No more acting on the wrong task by mistake! #+begin_src emacs-lisp ;; Always hilight the current agenda line (add-hook 'org-agenda-mode-hook '(lambda () (hl-line-mode 1))) #+end_src *** Remove tasks with dates from the global todo lists Tasks with dates (=SCHEDULED:=, =DEADLINE:=, or active dates) show up in the agenda when appropriate. Use the following settings to remove these tasks from the global todo lists. The idea here is the agenda has date-related items and the global todo lists have everything else. Keeping tasks only one list only prevents having to review tasks more than once when browsing the lists. Tasks with dates are scheduled into the future sometime and you don't need to deal with them until the date approaches. #+begin_src emacs-lisp ;; 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) #+end_src *** Use the Diary for Holidays only I don't use the emacs Diary for anything but I like seeing the holidays on my agenda. This helps with planning for those days when you're not supposed to be working. #+begin_src emacs-lisp (setq org-agenda-include-diary nil) #+end_src I don't have a =~/diary= file anymore. I include holidays from the calendar in my =todo.org= file as follows: : #+FILETAGS: HOME : * Appointments : :PROPERTIES: : :CATEGORY: Appt : :ARCHIVE: %s_archive::* Appointments : :END: : ** Holidays : :PROPERTIES: : :Category: Holiday : :END: : %%(org-calendar-holiday) : ** Some other Appointment : ... *** Searches include archive files I keep a single archive file for each of my org-mode project files. This allows me to search the current file and the archive when I need to dig up old information from the archives. I don't need this often but it sure is handy on the occasions that I do need it. #+begin_src emacs-lisp ;; Include agenda archive files when searching for things (setq org-agenda-text-search-extra-files (quote (agenda-archives))) #+end_src *** Agenda view tweaks The following agenda customizations control - display of repeating tasks - display of empty dates on the agenda - task sort order - start the agenda weekly view with =today= - display of the grid - habits at the bottom Here are the =.emacs= settings: #+begin_src emacs-lisp ;; 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) #+end_src ** Checklist handling 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= #+begin_src emacs-lisp (load "~/git/org-mode/contrib/lisp/org-checklist") #+end_src 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 =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. ** Handling blocked tasks 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: #+begin_src emacs-lisp (setq org-enforce-todo-dependencies t) #+end_src 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. ** Org Task structure and presentation This section describes various org-mode settings I use to control how tasks are displayed while I work on my org mode files. *** Controlling display of leading stars on headlines Org-mode has the ability to show or hide the leading starts on task headlines. It's also possible to have headlines at odd levels only so that the stars and heading task names line up in sublevels. I don't hide leading stars - I want to see the heading levels explicitly. When I tried the hide leading stars setting I found myself typing ' *' when adding a new heading and then the font lock shows I messed up and created a list instead. To make org show leading stars use #+begin_src emacs-lisp (setq org-hide-leading-stars nil) #+end_src emacs-lisp *** Show headings at odd levels only or odd-even levels I've converted my files between odd-levels-only and odd-even using the functions =org-convert-to-odd-levels= and =org-convert-to-oddeven-levels= functions a number of times. I ended up going back to odd-even levels to reduce the amount of leading whitespace on tasks. I didn't find that lining up the headlines and tasks in odd-levels-only to be all that helpful. #+begin_src emacs-lisp (setq org-odd-levels-only nil) #+end_src *** Handling blank lines Blank lines are evil :). They keep getting inserted in between headlines and I never want to see them in collapsed (contents) views. When I use =TAB= to fold (cycle) tasks I don't want to see any blank lines. The following setting hides all blank lines inside folded contents of a tasks: #+begin_src emacs-lisp (setq org-cycle-separator-lines 0) #+end_src I find extra blank lines in lists and headings a bit of a nuisance. To get a body after a list you need to include a blank line between the list entry and the body -- and indent the body appropriately. Most of my lists have no body detail so I like the look of collapsed lists with no blank lines better. The following setting prevents creating blank lines before list items and headings: #+begin_src emacs-lisp (setq org-blank-before-new-entry (quote ((heading) (plain-list-item)))) #+end_src *** Adding new tasks quickly without disturbing the current task content To create new headings in a project file it is really convenient to use C-S-RET. This inserts a new headline. With the following setting #+begin_src emacs-lisp (setq org-insert-heading-respect-content t) #+end_src Org adds the new heading after the content of the current item. This lets you hit C-S-RET in the middle of an entry and the new heading is added after the body of the current entry. I personally have =org-insert-heading-respect-content= set to =nil= now since I create blocks of text without structure first and then add headings in the middle to organize the text. I found jumping to the end (respecting content) was slowing me down since I don't normally have a lot of blank lines in the middle of my text. *** Notes at the top I enter notes for tasks with =C-c C-z= (or just =z= in the agenda). Changing tasks states also sometimes prompt for a note (e.g. moving to =WAITING= prompts for a note and I enter a reason for why it is waiting). These notes are saved at the top of the task so unfolding the task shows the note first. #+begin_src emacs-lisp (setq org-reverse-note-order nil) #+end_src *** Searching and showing results Org-mode's searching capabilities are really effective at finding data in your org files. =C-c / /= does a regular expression search on the current file and shows matching results in a collapsed view of the org-file. I have org-mode show the hierarchy of tasks above the matched entries and also the immediately following sibling task (but not all siblings) with the following settings: #+begin_src emacs-lisp (setq org-show-following-heading t) (setq org-show-hierarchy-above t) (setq org-show-siblings nil) #+end_src This keeps the results of the search relatively compact and mitigates accidental errors by cutting too much data from your org file with =C-k=. Cutting folded data (including the ...) can be really dangerous since it cuts text (including following subtrees) which you can't see. For this reason I always show the following headline when displaying search results. *** Editing and Special key handling Org-mode allows special handling of the C-a, C-e, and C-k keys while editing headlines. I also use the setting that pastes (yanks) subtrees and adjusts the levels to match the task I am pasting to. See the docstring (=C-h v org-yank-adjust-subtrees=) for more details on each variable and what it does. #+begin_src emacs-lisp (setq org-special-ctrl-a/e t) (setq org-special-ctrl-k t) (setq org-yank-adjusted-subtrees t) #+end_src ** Attachments 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: #+begin_src emacs-lisp (setq org-id-method (quote uuidgen)) #+end_src 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 Agenda Visibility 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: #+begin_src emacs-lisp (setq org-deadline-warning-days 30) #+end_src 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. ** Exporting Tables to CSV 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: #+begin_src emacs-lisp (setq org-table-export-default-format "orgtbl-to-csv") #+end_src lisp 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 #+begin_src csv One,Two,Three 1,1,2 3,6,5 fred,kpe,mary 234.5,432.12,324.3 #+end_src ** Visiting links 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. #+begin_src emacs-lisp (setq org-link-frame-setup (quote ((vm . vm-visit-folder-other-frame) (gnus . gnus-other-frame) (file . find-file-other-window)))) #+end_src 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 :) ** Logging stuff Most of my logging is controlled by the global =org-todo-keywords= My logging settings are set as follows: #+begin_src emacs-lisp (setq org-log-done (quote time)) (setq org-log-into-drawer t) #+end_src With =org-todo-keywords= set as #+begin_src emacs-lisp (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@)")))) #+end_src 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. ** Limiting time spent on tasks 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 :) ) #+begin_src emacs-lisp (setq org-clock-sound "/usr/local/lib/alert1.wav") #+end_src 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. ** Habit Tracking 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. #+begin_src emacs-lisp ; 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) #+end_src ** Habits only log DONE state changes 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: ** Automatically Mark Habits Done on Clock In I clock everything so I clock habits too. Clocking is completely manual and separate from todo state changes -- so marking a task =DONE= does not stop the clock. I need to manually stop the clock or clock something else in to change what is clocking. This allows me to mark habits as done as soon as I clock them in. I'm working on a habit and as far as I'm concerned it's done for today. I don't need to manually go back and mark it done later -- that's just extra work. Here's my setup for automatically marking habits done: #+begin_src emacs-lisp ;; Auto mark habits done on clock in ;; (defun bh/mark-habit-done-on-clock-in () (interactive) (when (org-is-habit-p) (org-todo 'done))) (add-hook 'org-clock-in-hook 'bh/mark-habit-done-on-clock-in) #+end_src ** Auto revert mode 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. #+begin_src emacs-lisp (setq global-auto-revert-mode t) #+end_src ** Handling Encryption 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: #+begin_src emacs-lisp (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") #+end_src =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. ** Speed Commands 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. #+begin_src emacs-lisp (setq org-use-speed-commands t) (setq org-speed-commands-user (quote (("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)))) #+end_src 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. ** Org Protocol [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 [[id:9507648b-dbfc-4ba1-96c2-36e8ba15cbd0][Remember Templates]]. #+begin_src emacs-lisp (require 'org-protocol) #+end_src 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 [[http://orgmode.org/worg/org-contrib/org-protocol.php#sec-9][Keybindings for Firefox]]. ** Add final newline when saving files #+begin_src emacs-lisp (setq require-final-newline t) #+end_src ** Insert inactive timestamps 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 the timestamp automatically added when I create the headline. I have a function that is run by an org-mode hook to automatically insert the inactive timestamp whenever a headline is created. #+begin_src emacs-lisp (defun bh/insert-inactive-timestamp () (interactive) (save-excursion (insert "\n") (org-cycle) (org-insert-time-stamp nil t t nil nil nil))) (add-hook 'org-insert-heading-hook 'bh/insert-inactive-timestamp) #+end_src Everytime I create a heading with =M-RET= or =M-S-RET= the hook invokes the function and it inserts an inactive timestamp like this : ** : [2009-11-22 Sun 18:45] This keeps an automatic record of when tasks are created which I find very useful. I also have a short cut key defined to invoke this function on demand so that I can insert the inactive timestamp anywhere on demand. #+begin_src emacs-lisp (global-set-key (kbd " t") 'bh/insert-inactive-timestamp) #+end_src ** Return follows links 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. #+begin_src emacs-lisp (setq org-return-follows-link t) #+end_src * Things I Don't Use This is a partial list of things I know about but do not use. =org-mode= is huge with tons of features. There are features out there that I don't know about yet or haven't explored so this list is not going to be complete. ** Task Priorities 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 #+begin_src emacs-lisp (setq org-enable-priority-commands nil) #+end_src ** Archive Sibling 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) ** Cycling plain lists Org mode can fold (cycle) plain lists. I don't use this feature. #+begin_src emacs-lisp (setq org-cycle-include-plain-lists nil) #+end_src * Using Git for Automatic History, Backups, and Synchronization :PROPERTIES: :CUSTOM_ID: GitSync :END: Editing folded regions of your org-mode file can be hazardous to your data. My method for dealing with this is to put my org files in a =Git= source repository. My setup saves all of my org-files every hour and creates a commit with my changes automatically. This lets me go back in time and view the state of my org files for any given hour over the lifetime of the document. I've used this once or twice to recover data I accidentally removed while editing folded regions. ** Automatic Hourly Commits My Emacs setup saves all org buffers at 1 minute before the hour using the following code in my =.emacs= #+begin_src emacs-lisp (run-at-time "00:59" 3600 'org-save-all-org-buffers) #+end_src 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: #+begin_example 0 * * * * ~/bin/org-git-sync.sh >/dev/null #+end_example *** ~/bin/org-git-sync.sh Here is the shell script I use to create a =git= commit for each of my org-repositories. This loops through multiple repositories and commits any modified files. I have the following org-mode repositories: - org for all of my organization project files and todo lists - doc-norang.ca for any changes to documents under http://doc.norang.ca/ - www.norang.ca for any changes to my other website http://www.norang.ca/ This script does not create empty commits - =git= only creates a commit if something was modified. #+begin_src sh #!/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 #+end_src sh I use the following =.gitignore= file in my org-mode =git= repositories to keep export generated files out of my =git= repositories. If I include a graphic from some other source than ditaa or graphviz then I'll add it to the repository manually. By default all PNG graphic files are ignored (since I assume they are produced by ditaa during export) #+begin_example core core.* ,*.html ,*~ .#* \#*\# ,*.txt ,*.tex ,*.aux ,*.dvi ,*.log ,*.out ,*.ics ,*.pdf ,*.xml ,*.org-source ,*.png ,*.toc #+end_example ** Git - Edit files with confidence 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. ** USB Stick synchronization 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 #+begin_src sh #!/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 #+end_src Here is the =usb-git-pull= script #+begin_src sh #!/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 #+end_src Here is the =usb-git-push= script #+begin_src sh #!/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 #+end_src Here is the =usb-git-missing= script #+begin_src sh #!/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 #+end_src