2 #+OPTIONS: H:2 num:t toc:t \n:nil @:t ::t |:t ^:t *:t TeX:t
3 #+EMAIL: carsten.dominik@gmail.com
6 #+TITLE: Org-mode Frequently Asked Questions
7 #+INFOJS_OPT: view:info toc:1 path:http://orgmode.org/worg/code/org-info-js/org-info.js tdepth:1 ftoc:t buttons:0 mouse:underline
8 #+OPTIONS: H:3 num:nil toc:t \n:nil @:t ::t |:t ^:{} -:t f:t *:t TeX:t LaTeX:t skip:nil d:(HIDE) tags:not-in-toc
10 [[file:index.org][{Back to Worg's index}]]
14 Welcome to the Org-mode FAQ.
16 You can navigate the FAQ by clicking on any of the topics in the Table
19 If your browser supports JavaScript, you can...
21 - move through the topics by typing "=n=" (next) and "=p=" (previous).
23 - see an outline view of the FAQ by typing "=m=" or clicking "=toggle
26 - search the FAQ by typing "=s=" (basic search) or "=o=" (occur tree).
28 - see a full list of navigation commands by typing "=?=" or clicking
32 ** Can I implement a GTD workflow with Org-mode?
33 #<<GTD-workflow-with-Org-mode>>
35 Yes, you can. Check for discussions and pointers [[http://orgmode.org/worg/org-gtd-etc.php][here]].
37 ** What is the difference between Org and TaskPaper?
38 #<<Org-and-TaskPaper>>
40 There is really no difference. Org is as /simple/ as [[http://hogbaysoftware.com/products/taskpaper][TaskPaper]]. It
41 is just that, when using Org within Emacs, it lets you do many things
42 that you wouldn't be able to do with TaskPaper. Yes, TaskPaper is
43 fiddle-proof and people using Emacs tends to like fiddling (which is
44 orthogonal to the idea of using todo-list efficiently), but this is
45 just a matter of discipline and common sense, not one of Org's design.
47 Read [[http://article.gmane.org/gmane.emacs.orgmode/6224][Carsten's enlightening statement]] on this.
48 ** What is the meaning of the Unicorn on Org's website?
51 This was /Bastien Guerry's/ idea, and his friend /Christophe
52 Bataillon/ designed the unicorn logo for us. Bastien writes why he
56 The first reason is not linked to the animal, but to the sounding of the
57 word "Unicorn" - because Org gives you a /uni/que way of producing files
58 in several format (HTML, LaTeX, etc.)
60 The second reason is that a Unicorn doesn't really exist, it is just
61 something you can dream about, and make others believe it does exist.
62 Just like the perfect organizer.
65 Here are some more ideas why I think this is a good fit:
67 - Org-mode is the UNICs of ORgaNizers.
69 - Org-mode is an Emacs mode, so it makes sense to use an animal
70 /somehow/ similar or related to the gnu used for GNU Emacs.
72 - Org-mode is meant to show you the way, and an animal with two horns
73 can not do this very well, can it?
75 - Unicorn tears are said to reverse petrification, and wasn't this how
76 we all felt before getting to some degree of time and task
79 - It will take forever to learn everything there is to know about a
82 - A unicorn is a fabulous creature. Org-mode wants to be a fabulous
85 - A unicorn can lose a fight against the lion and still live to save
86 the day when the witches strike (/Stardust/ by Neil Gaiman).
88 There was a [[http://thread.gmane.org/gmane.emacs.orgmode/11641/focus%3D11641][thread about unicorns]] on the mailing list, [[http://thread.gmane.org/gmane.emacs.orgmode/11641/focus%3D11641][Christopher
89 Suckling]] posted a link showing how to make a simple foldable unicorn,
90 and [[http://article.gmane.org/gmane.emacs.orgmode/11735][Tim Burt]] made a very compilcated one, see the picure below.
92 #+CAPTION: Folded unicorn. Made, and dedicated to Org-mode, by Tim Burt
93 [[http://farm4.static.flickr.com/3374/3319131381_b5bb2040fd.jpg]]
96 ** How do I keep current with Org mode development?
97 #<<keeping-current-with-Org-mode-development>>
99 Org mode is developed in [[http://en.wikipedia.org/wiki/Git_(software)][Git]]. You can keep up-to-date with Org
100 mode developement by cloning Org mode repository and refreshing
101 your copy with latest changes whenever you wish. You only need to
102 use two Git commands (clone and pull.) Here are the steps in
103 brief (please customize locations to suit your setup):
105 1. Select a location to house the Org mode repository (approx. 40
106 MB; includes documentation, compiled elisp files and history
107 going all the way back to v4.12a)
109 : $ mkdir $HOME/elisp && cd $HOME/elisp
111 2. Clone the Org mode Git repository.
113 Recommended approach:
115 : $ git clone git://repo.or.cz/org-mode.git
117 Alternate approach if you are behind a firewall that allows only
118 HTTP (can be quite slow):
120 : $ git clone http://repo.or.cz/r/org-mode.git
122 3. Compile and install Org mode and build documentation.
124 : $ cd org-mode && make && make doc && make install
126 Please note that you can choose to /not/ compile at all and run
127 using source =.el= files only. Compiled files speed things up.
129 4. This is where you configure Org mode with Emacs. Please refer
130 to [[./org-tutorials/index.org][Org tutorials]].
132 5. Keeping up-to-date.
134 Cloning the repository is a one time activity. From this point
135 onwards you only need to /pull/ the latest changes.
137 : $ cd $HOME/elisp/org-mode
141 : $ git pull && make clean && make && make doc && make install
143 6. You should restart org mode to have the changes take effect (if
144 you are not rebooting Emacs.) Also since the intention is to
145 "keep up" with Org mode, you should visit ChangeLog and updated
146 sections of documentation for latest updates (use =git log=.)
148 7. As you use your repository over time it will accumulate loose objects.
149 You can reduce the total size of your git repository with
153 which will consolidate loose git objects into pack files. This
154 reduces the size of the repository and speeds up data access to
157 ** How can I keep local changes and still track Org mode development?
158 #<<keeping-local-changes-current-with-Org-mode-development>>
160 Say you want to make minor changes to the Makefile to reflect your
161 location for =emacs=.
163 Create a local branch for your changes on top of origin/master as
166 : $ git checkout -b local origin/master
167 : $ git config branch.local.rebase true
168 : # Make your changes to the Makefile and create a new commit
170 : $ git commit -m 'My local Makefile configurations'
171 : # Update git to a newer version
174 Now each time you pull new commits from the distribution repository
175 your local commits will be rewound and replayed on top of the new
180 You would normally work on your =local= branch which includes your
181 custom commits; there's no need to switch back to the =master=
186 Here is an example of dealing with conflict resolution during git pull.
188 If you get a conflict during a =git pull= you will need to edit the
189 file with the conflict to fix up the conflicting lines and then tell
190 git that you have resolved the conflict.
192 Conflict resolution goes something like this:
194 1. =git pull= fails with a conflict
196 3. =git add= the file to mark the conflict resolved
197 4. =git rebase --continue=
198 5. lather, rinse, and repeat 2-4 as needed
200 For this example we have the following Makefile:
210 and we need to change the =EMACS=emacs= line to =EMACS=myemacs= to
211 make it work well on our system.
215 - create a local branch for our work
217 : $ git checkout -b local origin/master
218 : $ git config branch.local.rebase true
220 This marks the branch so that all local commits on it are rebased
221 on top of any new commits we get in origin/master during a =git
224 - Make our custom changes
226 Edit the makefile so it looks like this:
236 - Create a commit with our custom changes
238 : $ git commit -m 'My local Makefile configurations'
240 - Later we do a =git pull= but that fails with conflicts.
243 : remote: Counting objects: 5, done.
245 : Patch failed at 0001.
247 : When you have resolved this problem run "git rebase --continue".
248 : If you would prefer to skip this patch, instead run "git rebase --skip".
249 : To restore the original branch and stop rebasing run "git rebase --abort".
251 - Fix the conflict in your favourite editor
253 Conflict markers look like this:
255 : <<<<<<< HEAD:Makefile
259 : >>>>>>> Change emacs location:Makefile
261 This attempted =git pull= caused a conflict. Fire up your
262 favourite editor and fix the conflict in the Makefile. The
263 conflict markers are <<<<<<<<<< , ======= , and >>>>>>>>>>. Fix
264 the Makefile appropriately and delete the conflict markers. You
265 already edited these lines earlier so fixing it should be trivial.
267 In this case we changed =EMACS=emacs= to =EMACS=myemacs= and
268 upstream changed =EMACS=emacs= to =EMACS=emacs22=. Just fix the
269 file and save it by deleting the conflict markers and keeping the
270 code you need (in this case the =EMACS=myemacs= line which we
271 originally modified.)
273 - Mark the file's conflict resolved
277 You use =git add= because you are adding new content to be tracked - you're not adding a file, but you are adding changes in content.
279 - Continue the rebase operation
281 : $ git rebase --continue
283 If any other conflicts arise you fix them the same way - edit the file, mark the conflict resolved, and continue.
285 At anytime during the rebase conflict resolution you can say "oops this is all wrong - put it back the way it was before I did a pull"
287 : $ git rebase --abort
290 ** Can I use the editing features of org-mode in other modes?
291 #<<use-editing-features-in-other-modes>>
293 Not really---but there are a few editing features you can use in
296 - For tables there is =orgtbl-mode= which implements the table
297 editor as a minor mode. (To enable, type =M-x orgtbl-mode=)
298 - For ordered lists there is =orgstuct-mode= which allows for easy
299 list editing as a minor mode. (To enable, type =M-x
302 You can activate these modes automatically by using hooks:
304 : (add-hook 'mail-mode-hook 'turn-on-orgtbl)
305 : (add-hook 'mail-mode-hook 'turn-on-orgstruct)
307 For footnotes, there is the function =org-footnote-action=, which
308 works in non-org buffers. This function is a powerful tool for
309 creating and sorting footnotes. To use it globally, you can add the
310 following keybinding to your =.emacs= file (requires Org 6.17 or
313 : (global-set-key (kbd "C-c f") 'org-footnote-action)
315 For other features you need to switch to Org-mode temporarily, or
316 prepare text in a different buffer.
318 ** Why isn't feature "X" working the way it is described in the manual?
319 #<<making-sure-org-mode-is-up-to-date>>
321 Org-mode develops very quickly. There have been a great many changes,
322 for instance, since the release of Emacs 22, which shipped with
323 version 4.67d of org-mode. (Emacs 23 is expected to ship with version
326 Many of the users on the org-mode mailing list are using either a
327 recent release of org-mode or the
328 [[http://orgmode.org/index.html#sec-3.2][development version of
329 org-mode from the git repository]].
331 If some settings and features aren't working the way you expect, make
332 sure that the version of the manual you are consulting matches the
333 version of org-mode you are using.
335 - You can check which version of org-mode you are using by
336 selection =Org --> Documentation --> Show Version= in the Emacs
339 - The [[http://orgmode.org/manual/index.html][online manual]] at [[http://orgmode.org][orgmode.org]] corresponds to the most recent
342 - The [[http://www.gnu.org/software/emacs/manual/html_node/org/index.html][manual]] at [[http://www.gnu.org][www.gnu.org]] corresponds to the version of org-mode
343 released with the latest official Gnu Emacs release (Emacs 22 and
344 org-mode 4.67d as of February 2009). Note: compared with the
345 manual at the orgmode.org, the manual at www.gnu.org is
346 considerably out of date.
348 For instructions on how to stay current with org-mode, consult [[keeping-current-with-Org-mode-development][this
349 FAQ]] or follow the instructions on [[http://orgmode.org][the official org-mode site]].
351 ** Can I get the visibility-cycling features in outline-mode and outline-minor-mode?
352 #<<use-visibility-cycling-in-outline-mode>>
354 Yes, these functions are written in a way that they are independent of
355 the outline setup. The following setup provides standard Org-mode
356 functionality in outline-mode on =TAB= and =S-TAB=. For
357 outline-minor-mode, we use =C-TAB= instead of =TAB=,
358 because =TAB= usually has mode-specific tasks.
360 #+BEGIN_SRC emacs-lisp
361 (add-hook 'outline-minor-mode-hook
363 (define-key outline-minor-mode-map [(control tab)] 'org-cycle)
364 (define-key outline-minor-mode-map [(shift tab)] 'org-global-cycle)))
365 (add-hook 'outline-mode-hook
367 (define-key outline-mode-map [(tab)] 'org-cycle)
368 (define-key outline-mode-map [(shift tab)] 'org-global-cycle)))
371 Or check out /outline-magic.el/, which does this and also provides
372 promotion and demotion functionality. /outline-magic.el/ is
373 available at [[http://www.astro.uva.nl/~dominik/Tools/OutlineMagic][Outline Magic]].
375 ** How can I keep track of changes in my Org files?
376 #<<track-of-changes-in-Org-files>>
378 Use git to track the history of the files, use a cronjob to check in
379 changes regularly. Such a setup is described by Bernt Hansen
380 in [[http://article.gmane.org/gmane.emacs.orgmode/6233][this message]] on [[http://dir.gmane.org/gmane.emacs.orgmode][emacs-orgmode]].
382 ** Can I use Org-mode as the default mode for all README files?
383 #<<Org-mode-as-default-mode>>
385 Add the following to your .emacs file:
387 : (add-to-list 'auto-mode-alist '("README$" . org-mode))
389 You can even make it the default mode for any files with unspecified
392 : (setq default-major-mode 'org-mode)
394 ** Can I use ido.el for completing stuff in Org?
397 Yes, you can. If you are an ido user and ido-mode is active, the
398 following setting will make Org use =ido-completing-read= for most
399 of its completing prompts.
401 : (setq org-completion-use-ido t)
403 ** Should I use one big org file or multiple files?
404 #<<how-to-organize-org-mode-files>>
406 Org-mode is flexible enough to accomodate a variety of organizational
407 and time management schemes. Org's
408 [[http://orgmode.org/manual/Document-Structure.html#Document-Structure][outline
409 cycling and convenient editing and navigation commands]] make it
410 possible to maintain all of your projects and notes in a single file.
411 But org-mode's [[http://orgmode.org/manual/Hyperlinks.html#Hyperlinks][quick and easy hyperlinks]], along with [[http://orgmode.org/manual/Refiling-notes.html#Refiling-notes][easy refiling of
412 notes and todos]], also make it a delight to maintain a private "wiki"
413 consisting of multiple files.
415 No matter how you organize your org files, org-mode's agenda commands
416 make it easy to search all your notes and gather together crucial data
419 Moreover, several org-mode settings can be configured either globally
420 in your =.emacs= file or locally (per file or per outline tree). See
421 the [[http://orgmode.org/manual/index.html#Top][manual]] for more details. For an example of local customizations
422 see [[limit-agenda-with-category-match][this FAQ]].
424 Here are a few ideas for organizing org-mode files:
426 - A single file for all your projects and notes.
427 - One file per project.
428 - One file per client.
429 - One file per area of responsibility or type of work (e.g.,
430 household, health, work, etc.).
431 - One file for projects, one for appointments, one for reference
432 material, one for someday/maybe items, etc.
433 - A wiki of hyperlinked files that grows and adapts to meet your
436 For more ideas, see some of the links on the [[file:org-tutorials/index.org][org-tutorial index]] or
437 [[file:org-gtd-etc.org][this page on org-mode and GTD]].
439 ** Why doesn't C-c a call the agenda? Why don't some org keybindings work?
440 #<<setting-global-keybindings>>
442 Org-mode has a few global keybindings that the user must set
443 explicitly in an =.emacs= file. These keybindings include the
444 customary shortcut for calling the agenda (=C-c a=). If nothing
445 happens when you type =C-c a=, then make sure that the following lines
446 are in your =.emacs= file:
448 #+BEGIN_SRC emacs-lisp
449 ;; The following lines are always needed. Choose your own keys.
450 (add-to-list 'auto-mode-alist '("\\.org\\'" . org-mode))
451 (global-set-key "\C-cl" 'org-store-link)
452 (global-set-key "\C-ca" 'org-agenda)
453 (global-set-key "\C-cb" 'org-iswitchb)
456 You may, of course, choose whatever keybindings work best for you
457 and do not conflict with other modes.
459 Please see [[http://orgmode.org/manual/Activation.html][this section of the manual]] if you have additional
462 ** Why aren't some of the variables I've customized having an effect?
463 #<<load-org-after-setting-variables>>
465 Some org variables have to be set before org.el is loaded or else they
466 will not work. (An example is the new variable
467 =org-enforce-todo-dependencies=.)
469 To make sure all your variables work you should not use =(require
470 'org)=. Instead use the following setting:
472 : (require 'org-install)
474 You should also make sure that you do not require any other =org-...=
475 files in your =.emacs= file before you have set your org variables,
476 since these will also cause org.el to be loaded. To be safe, load org
477 files *after* you have set your variables.
480 ** When I try to use Org-mode, I always get the error message =(wrong-type-argument keymapp nil)=
481 #<<wrong-type-argument-keymapp>>
483 This is a conflict with an outdated version of the /allout.el/, see
484 the [[http://orgmode.org/manual/Conflicts.html#Conflicts][Conflicts]] section in the manual
486 ** Org-mode takes over the S-cursor keys. I also want to use CUA-mode, is there a way to fix this conflict?
489 Yes, see the [[http://orgmode.org/manual/Conflicts.html#Conflicts][Conflicts]] section of the manual.
491 ** Org-mode takes over the S-cursor keys. I also want to use windmove.el, is there a way to fix this conflict?
494 Yes, see the [[http://orgmode.org/manual/Conflicts.html#Conflicts][Conflicts]] section of the manual.
496 ** Org behaves strangely: some keys don't work, some features are missing, my settings have no effect, ...
499 When this sort of things happen, it probably is because Emacs is loading an old version of Org-mode instead of the one you expected. Check it with =M-x org-version=.
501 This happens because Emacs loads first the system org-mode (the one included with Emacs) before the one in your directory. Check the =load-path= variable; you might see that your org-mode appears /after/ the system-wide path; this is bad.
503 You should add your directories to the =load-path= at the beginning:
505 : (add-to-list 'load-path "~/.emacs.d/org-mode/lisp") (require 'org-install)
507 Function =add-to-list= adds at the beginning. Don't use =append= because it appends at the end. Also be sure to use =(require 'org-install)= and not =(require 'org)=.
509 This wrong version loading may also happen if you have a byte-compiled =org.elc= from an old version together with a new =org.el=. Since Emacs prefers loading byte-compiled files (even if the =.el= is newer), it will load the old Org-mode.
511 ** Why doesn't org-batch-agenda work under Win32?
512 #<<org-batch-agenda-under-win32>>
514 When I run the example batch files to print my agenda to the console
515 under Win32 I get the failure:
517 : End of file during parsing
519 and no agenda is printed.
521 The problem is the use of single quotes surrounding the eval in the
522 emacs command-line. This gets confused under Win32. All string
523 parameters with spaces must be surrounded in double quotes. This means
524 that double quotes being passed to the eval must be escaped.
526 Therefore, instead of the following:
528 : <path to emacs>\emacs.exe -batch -l ~/_emacs_org \
529 : -eval '(org-batch-agenda "a")'
531 you need to use the following:
533 : <path to emacs>\emacs.exe -batch -l ~/_emacs_org \
534 : -eval "(org-batch-agenda \"a\")"
536 (all on one line, of course).
539 ** Can I have two windows on the same Org-mode file, with different outline visibilities?
540 #<<indirect-buffers>>
542 You may use /indirect buffers/ which do exactly this. See the
543 documentation on the command =make-indirect-buffer=.
545 Org-mode has built-in commands that allow you create an indirect
546 buffer from a subtree of an outline. To open a subtree in new
547 window, type =C-c C-x b=. Any changes you make in the new window
548 will be saved to the original file, but the visibility of both
549 buffers will remain independent of one another.
551 For multiple indirect buffers from the same file, you must use the
552 prefix =C-u= when creating the second (or third) buffer. Otherwise
553 the new indirect buffer will replace the old.
555 You can also create an independent view of an outline subtree by
556 typing =b= on an item in the agenda.
558 ** Emacs outlines are unreadable. Can I get rid of all those stars?
559 #<<Emacs-outlines-are-unreadable>>
561 See the section [[http://orgmode.org/manual/Clean-view.html#Clean-view][Clean outline view]] in the manual.
562 ** C-k is killing whole subtrees! I lost my work!
563 #<<C-k-is-killing-subtrees>>
565 =(setq org-special-ctrl-k t)= before losing your work.
567 ** Why aren't commands working on regions?
568 #<<transient-mark-mode>>
570 Some org-mode commands, such as M-right and M-left for demoting or
571 promoting headlines (see [[demote-multiple-headlines][this FAQ]]), can be applied to entire regions.
572 These commands, however, will only work on active regions set with
573 [[http://www.gnu.org/software/emacs/manual/html_node/emacs/Transient-Mark.html#Transient-Mark][transient mark mode]]. Transient mark mode is enabled by default in
574 Emacs 23. To enable it in earlier versions of emacs, put the following
575 in your =.emacs= file:
577 : (transient-mark-mode 1)
579 Alternatively, you may turn off transient mark mode and use [[http://www.gnu.org/software/emacs/manual/html_node/emacs/Momentary-Mark.html][a
580 momentary mark]] (=C-<SPC> C-<SPC>=).
582 ** Why is a blank line inserted after headlines and list items?
584 :ID: 2463F4D8-F686-4CF3-AA07-08976F8A4972
586 #<<blank-line-after-headlines-and-list-items>>
588 In org-mode, typing =M-RET= at the end of a headline will create a new
589 headline of the same level on a new line. The same is true for plain
590 lists. By default org-mode uses context to determine if a blank line
591 should be inserted after each headline or plain list item when =M-RET=
592 is pressed. For instance, if a there is a blank line before a
593 headline, then typing =M-RET= at the end of the line will insert a
594 blank line before the new headline. For instance, hitting =M-RET=
595 at the end of "Headline Two" below inserts a new headline without a
602 If there is a blank line between Headline One and Headline Two,
603 however, the results will be as follows:
611 If you do not like the default behavior you can change it with the
612 variable =org-blank-before-new-entry=. You can set headings and/or
613 plain lists to auto (the default setting), t (always), or nil (never).
615 ** How can I promote or demote multiple headlines at once?
616 #<<demote-multiple-headlines>>
618 If you have a long list of first level headlines that you'd like to
619 demote to second level headlines, you can select the headlines as a
620 region and then hit =M-<right>= to demote all the headlines at once.
622 Note: =M-S-<right>= will not work on a selected region. Its use is to
623 demote a single subtree (i.e., a headline and all sub-headlines).
625 If M-<right> doesn't seem to work, make sure transient mark mode is
626 enabled. See [[transient-mark-mode][this FAQ]].
629 ** How can I cycle through the TODO keyword of an entry?
630 #<<cycle-TODO-keywords>>
632 =C-c C-t= or =S-<left/right>= is what you need.
634 ** How do I track state changes for tasks in Org?
635 #<<track-state-changes-for-tasks>>
637 Take a look at the [[http://thread.gmane.org/gmane.emacs.orgmode/6082][post by Bernt Hansen]] for setting up TODO keyword
638 states and logging timestamps for task state changes.
640 ** Can I select the TODO keywords with a tag-like interface?
641 #<<select-TODO-keywords-with-tag-like-interface>>
643 Yes. Use =(setq org-use-fast-todo-selection t)=
645 If you want to set both your todos and your tags using a single
646 interface, then check out the variable
647 =org-fast-tag-selection-include-todo=.
649 See [[http://orgmode.org/manual/Fast-access-to-TODO-states.html][this section of the manual]] for more details.
651 ** How can I quickly set the tag of an entry?
652 #<<quickly-set-tag-of-entry>>
654 Use =C-c C-c= or =C-c C-q= on the headline. =C-c C-q= is useful for
655 setting tabs in a [[http://orgmode.org/manual/Remember.html#Remember][remember]] buffer, since =C-c C-c= is the default
656 keybinding for filing a note from the remember buffer.
658 You can set tags even more quickly by setting one of the character
659 shortcuts for [[http://orgmode.org/manual/Setting-tags.html#Setting-tags][fast tag selection]].
661 To set tag shortcuts for all org buffers, put something like the
662 following in your =.emacs= file (or create the same settings by
663 typing =M-x customize-variable RET org-tag-alist=):
665 : (setq org-tag-alist '(("computer" . ?c) ("office" . ?o) ("home" . ?h)))
667 To set tag shortcuts for a single buffer, put something like the
668 following at the top of your org file:
670 : #+TAGS: computer(c) office(o) home(h)
672 ** How can I change the colors of TODO keywords?
674 You can use the variable org-todo-keyword-faces. Here are some sample
677 #+begin_src emacs-lisp
678 (setq org-todo-keyword-faces
680 ("TODO" . (:foreground "firebrick2" :weight bold))
681 ("WAITING" . (:foreground "olivedrab" :weight bold))
682 ("LATER" . (:foreground "sienna" :weight bold))
683 ("PROJECT" . (:foreground "steelblue" :weight bold))
684 ("DONE" . (:foreground "forestgreen" :weight bold))
685 ("MAYBE" . (:foreground "dimgrey" :weight bold))
686 ("CANCELED" . shadow)
690 If you want to change the color of all active todos or all inactive
693 : M-x customize-face RET org-todo
694 : M-x customize-face RET org-done
696 You can also set values for each of these in your =.emacs= file:
698 : (set-face-foreground 'org-todo "firebrick2")
699 : (set-face-foreground 'org-done "forestgreen")
702 ** Why do I have to confirm the execution of each shell/elisp link?
703 #<<confirm-shell/elisp-link>>
705 The confirmation is there to protect you from unwantingly execute
706 potentially dangerous commands. For example, imagine a link
708 : [[shell:rm -rf ~/*][Google Search]]
710 In an Org-mode buffer, this command would look like /Google Search/,
711 but really it would remove your home directory. If you wish, you can
712 make it easier to respond to the query by setting
714 : (setq org-confirm-shell-link-function 'y-or-n-p
715 : org-confirm-elisp-link-function 'y-or-n-p).
717 Then a single keypress will be enough to confirm those links. It is
718 also possible to turn off this check entirely, but I strongly
719 recommend against this. Be warned.
721 ** Can I use RET or TAB to follow a link?
722 #<<RET-or-TAB-to-follow-link>>
726 : (setq org-return-follows-link t)
727 : (setq org-tab-follows-link t)
729 ** Can I keep mouse-1 clicks from following a link?
730 #<<mouse-1-following-link>>
732 Activating links with =mouse-1= is a new feature in Emacs 22, to make
733 link behavior similar to other applications like web browsers. If
734 you hold the mouse button down a bit longer, the cursor will be set
735 without following the link. If you cannot get used to this behavior,
736 you can (as in Emacs 21) use =mouse-2= to follow links and turn off
737 link activation for =mouse-1= with
739 : (setq org-mouse-1-follows-link nil)
741 ** How can I get completion of file names when creating a link?
742 #<<completion-of-file-links>>
744 You can use org-insert-link with a prefix argument:
748 You will be greeted with prompt in the minibuffer that allows for file
749 completion using your preferred Emacs method for finding files.
751 ** How can I insert an empty line before each newly inserted headline, but not before each newly inserted plain-list item?
752 #<<empty-line-before-each-new-headline-but-not-item>>
754 : (setq org-blank-before-new-entry
755 : '((heading . t) (plain-list-item . nil))
757 See also [[id:2463F4D8-F686-4CF3-AA07-08976F8A4972][Why is a blank line inserted after headlines and list items?]].
759 ** How can I convert itemized lists to enumerated lists?
760 #<<convert-itemized-to-enumerated-lists>>
762 You can use =C-c -= or =S-<left>/<right>= to cycle through the various
763 bullet headlines available for lists: =-, +, *, 1., 1)=.
765 See [[http://orgmode.org/manual/Plain-lists.html#Plain-lists][this section of the manual]] for more information.
767 ** How can I convert plain lists to headlines and vice versa?
768 #<<convert-plain-lists-to-headlines>>
770 To convert a plain list item or line to a headline, type =C-c *= on
771 the headline. This will make the line a subheading of the current
774 To convert a headline to a plain list item, type =C-c -= while the
775 cursor is on the headline.
777 To convert a headline to an unadorned line of text, type =C-c *= on
780 You can use query replace to accomplish the same things, as Bernt
781 Hansen explains in [[http://article.gmane.org/gmane.emacs.orgmode/10148][this mailing list post]].
783 ** Is there a good way to create a description list?
784 #<<description-lists>>
786 Yes, these are now built-in:
789 - item1 :: Description of this item 1
790 - item2 :: Description of this item 2
791 - item1 :: Description of this item 3
792 also in multiple lines
796 ** Can I plot data from a table?
797 #<<plotting-table-data>>
799 Yes, you can, using org-plot.el written by James TD Smith and now
800 bundled with Org. See [[http://orgmode.org/manual/Org-Plot.html#Org-Plot][the manual section about this]].
802 See also [[file:org-tutorials/org-plot.org][this excellent tutorial]] by Eric Schulte.
804 ** How can I fill a table column with incremental numbers?
805 #<<fill-table-column-with-incremental-numbers>>
807 Here is how: Use a field formula to set the first value in the column:
819 Then define a column formula in the second field:
831 After recomputing the table, the column will be filled with
841 ,#+TBLFM: $1=@-1 + 1::@2$1=1
844 Note that you could use arbitrary starting values and column formulas.
846 ** Why does my table column get filled with #ERROR?
847 #<<table-column-filled-with-ERROR>>
849 Org-mode tried to compute the column from other fields using a
850 formula stored in the =#+TBLFM:= line just below the table, and
851 the evaluation of the formula fails. Fix the fields used in the
852 formula, or fix the formula, or remove it!
854 ** How can I stop the table editor from creating new lines?
855 #<<table-editor-creates-new-lines>>
857 When I am in the last column of a table and just above a horizontal
858 line in the table, pressing TAB creates a new table line before the
859 horizontal line. To move to the line below the
860 horizontal line instead, do this:
862 Press =down= (to get on the separator line) and then =TAB=.
863 Or configure the variable
865 : (setq org-table-tab-jumps-over-hlines t)
867 ** How can I get table fields starting with "="?
868 #<<table-fields-starting-with-=>>
872 : (setq org-table-formula-evaluate-inline nil)
874 this will no longer happen. You can still use formulas using the
875 commands @<tt>C-c =@</tt> and @<tt>C-u C-c =@</tt>
877 ** How can I change the indentation of an entire table without fixing every line by hand?
878 #<<change-indentation-entire-table>>
880 The indentation of a table is set by the first line. So just fix the
881 indentation of the first line and realign with =TAB=.
883 ** In my huge table the realigning after each TAB takes too long. What can I do?
884 #<<table-realigning-after-TAB-takes-long>>
886 Either split the table into several by inserting an empty line every
887 100 lines or so. Or turn off the automatic re-align with
889 : (setq org-table-automatic-realign nil)
891 After this the only way to realign a table is to press =C-c C-c=. It
892 will no longer happen automatically, removing the corresponding delays
895 ** Recalculation of my table takes too long. What can I do?
896 #<<Recalculation-of-my-table-takes-too-long>>
898 Nothing, really. The spreadsheet in org is mostly done to make
899 calculations possible, not so much to make them fast. Since Org-mode
900 is firmly committed to the ASCII format, nothing is stopping you from
901 editing the table by hand. Therefore, there is no internal
902 representation of the data. Each time Org-mode starts a computation,
903 it must scan the table for special lines, find the fields etc. This
904 is slow. Furthermore, Calc is slow compared to hardware
905 computations. To make this work with normal editing, recalculation
906 is not happening automatically, or only for the current line, so that
907 the long wait for a full table iteration only happens when you ask
910 So for really complex tables, moving to a "real" spreadsheet may
911 still be the best option.
913 That said, there are some ways to optimize things in Org-mode, and I
914 have been thinking about moving a bit further down this line.
915 However, for my applications this has so far not been an issue at
916 all. If you have a good case, you could try to convince me.
918 ** =S-RET= in a table keeps increasing the copied numbers. How can I stop this?
919 #<<S-RET-in-a-table-increases-copied-numbers>>
921 Well, it is /supposed/ to be a feature, to make it easy to create a
922 column with increasing numbers. If this gets into your way, turn it
925 : (setq org-org-table-copy-increment nil)
928 ** Can I use the remember buffer to clock a customer phone call?
929 #<<use-remember-buffer-to-clock-phone-call>>
931 Yes, you can. Take a look at the [[http://thread.gmane.org/gmane.emacs.orgmode/5482][setup described by Bernt Hansen]]
932 and check out (in the same thread) what Nick Docos had to fix to
933 make Bernt's set-up work for him.
934 ** Can I automatically start the clock when opening a remember template?
935 #<<start-clock-when-opening-remember-template>>
937 Yes, this is possible. Use the following code and make sure that
938 after executing it, `my-start-clock-if-needed' is in
939 `remember-mode-hook' /after/ `org-remember-apply-template'.
941 : (add-hook 'remember-mode-hook 'my-start-clock-if-needed 'append)
942 : (defun my-start-clock-if-needed ()
944 : (goto-char (point-min))
945 : (when (re-search-forward " *CLOCK-IN *" nil t)
949 Then, when a template contains the key string CLOCK-IN, the clock
950 will be started. Starting with Org-mode version 5.20, the clock will
951 automatically be stopped when storing the remember buffer.
954 ** Isearch does not find string hidden in links. What can I do?
955 #<<isearch-in-links>>
957 M-x =visible-mode= will display the full link, making them searchable.
959 ** How can I reduce the amount of context shown in sparse trees?
960 #<<context-in-sparse-trees>>
962 Take a look at the following variables:
964 - =org-show-hierarchy-above=
965 - =org-show-following-headline=
966 - =org-show-siblings=
967 - =org-show-entry-blow=
969 which give command-dependent control over how much context is shown
970 by a particular operation.
972 ** How can I combine the results of two calls to =org-occur=?
973 #<<two-calls-to-org-occur>>
975 You can construct a regular expression that matches all targets you
976 want. Alternatively, use a =C-u= prefix with the second and any
977 further calls to =org-occur= to keep the current visibility and
978 highlighting in addition to the new ones.
981 ** How can I change the advanced warning time for deadlines?
982 ##<<warning-period-for-deadlines>>
984 Deadline warnings appear in the daily agenda view a specified number
985 of days before the deadline is due. The default setting is 14 days.
986 You can change this with the variable =org-deadline-warning-days=.
987 (See [[http://orgmode.org/manual/Deadlines-and-scheduling.html#Deadlines-and-scheduling][this section]] of the manual.)
991 : (setq org-deadline-warning-days 30)
993 would cause warnings for each deadline to appear 30 days in advance.
995 Naturally, you might not want warnings for all of your deadlines to
996 appear so far in advance. Thus, you can change the lead time for
997 individual items as follows:
999 : * TODO Get a gift for the party
1000 : DEADLINE: <2009-01-16 Fri -2d>
1002 The "-2d" above changes the lead time for this deadline warning to two
1003 days in advance. You can also use "w" for weeks and "m" for months.
1004 ** How can I postpone a task until a certain date?
1005 #<<deferring-tasks>>
1007 The easiest way to postpone a task is to schedule it in the future.
1008 For instance, typing =C-c C-s +2w= on a headline will push a task two
1009 weeks into the future, so that it won't show up on the daily agenda
1010 until two weeks from now.
1012 If you'd like to prevent the task from showing up on your global todo
1013 list, you have a couple of options.
1015 1. You can set the variable =org-agenda-todo-ignore-scheduled= to =t=.
1016 This will exclude any scheduled items from your global list of
1017 active todos (=C-c a t=). (The variable
1018 =org-agenda-todo-ignore-with-date= will exclude both scheduled and
1019 deadline items from your todo list).
1020 2. You can remove the todo keyword from the item (C-c C-t <SPC>). The
1021 item will still appear on your agenda two weeks from today, but it
1022 won't show up on your todo lists.
1023 ** Can I send myself an email containing tasks or other agenda info?
1024 #<<email-containing-tasks-or-other-agenda-info>>
1026 Yes. See [[http://article.gmane.org/gmane.emacs.orgmode/6112][this thread]] on the list.
1028 ** How can I limit the agenda view to my "work" tasks?
1029 #<<limit-agenda-with-tag-filtering>>
1031 It is often convenient to group org files into separate categories,
1032 such as "home" and "work" (or "personal" and "professional"). One
1033 of the main reasons for such classification is to create agenda
1034 views that are limited by type of work or area of responsibility.
1035 For instance, while at work, one may want to see only professional
1036 tasks; while away from work, one may want to see only personal
1039 One way to categorize files and tasks is to use a "#+FILETAGS"
1040 declaration at the top of each file, such as:
1044 As long as org-use-tag-inheritance is turned on, the filetags will
1045 be inherited by all tasks in the file. A file can have multiple
1046 filetags. And, of course, tags can be added to individual headings.
1048 Tasks can be quickly filtered by tag from within the agenda by
1049 typing "/" and the name of the tag. The full key sequence to filter
1050 for work items in an agenda view would be:
1052 : C-c a a / work [or a tag shortcut]
1054 ** How can I limit the agenda view to a particular category?
1055 #<<limit-agenda-with-category-match>>
1057 Another way to filter agenda views by type of work is to use a
1058 "#+CATEGORY" declaration at the top of each file, such as:
1062 Categories can also be added to individual headings within a file:
1069 All todos belonging to the category "work" can be found a with a
1070 simple tags-todo search:
1074 At the prompt, type:
1078 The same results can be achieved with custom agenda commands, such as:
1080 #+BEGIN_SRC emacs-lisp
1081 (setq org-agenda-custom-commands
1082 '(("h" tags-todo "CATEGORY=\"home\"")
1083 ("w" tags-todo "CATEGORY=\"work\"")
1084 ;; other custom agenda commands here
1088 ** How can include all org files in a directory in my agenda?
1089 #<<set-agenda-files-using-wildcards>>
1091 You can use the file-expand-wildcards function to all files ending in
1092 =org= in a directory to your agenda files list:
1094 : (setq org-agenda-files (file-expand-wildcards "~/org/*.org"))
1096 ** Why aren't items disappearing from my agenda once they are marked done?
1097 #<<removing-done-items-from-agenda>>
1099 If items remain on your daily/weekly agenda after they are marked
1100 done, check the configuration of the following variables:
1102 : org-agenda-skip-scheduled-if-done
1103 : org-agenda-skip-deadline-if-done
1104 : org-agenda-skip-timestamp-if-done
1108 : M-x customize-variable RET org-agenda-skip-scheduled-if-done
1110 If this variable is turned off (=nil=), then scheduled items will
1111 remain on the agenda even after they are marked done.
1113 If the variable is turned on (=t=), then scheduled items will
1114 disappear from the agenda after they are marked done.
1116 If these settings seem not to behave the way you expect, then make
1117 sure you understand [[scheduled-vs-deadline-vs-timestamp][the
1118 difference between SCHEDULED, DEADLINE, and timestamps]].
1120 ** What is the difference between SCHEDULED, DEADLINE, and plain timestamps?
1121 #<<scheduled-vs-deadline-vs-timestamp>>
1123 1. SCHEDULED items (set with =C-c C-s=) will appear on your agenda on
1124 the day they are scheduled and on every day thereafter until they
1125 are done. Schedule a task if you want to be reminded to do
1126 something beginning on a certain day and until it is done.
1128 : ** TODO Scheduled item
1129 : SCHEDULED: <2009-03-01 Sun>
1131 2. Items with a DEADLINE timestamp (set with =C-c C-d=) appear on your
1132 agenda in advance of the when they are due and remain on your
1133 agenda until they are done. Add a DEADLINE to an item if you want
1134 to make sure to complete it by a certain date. (The variable
1135 org-deadline-warning-days determines how far in advance items with
1136 deadlines will show up in the agenda. See [[warning-period-for-deadlines][this FAQ]] for more
1139 : ** TODO Item with a deadline
1140 : DEADLINE: <2009-01-20 Tue>
1142 3. An active timestamp (set with =C-c .=) will appear on your agenda
1143 only on the day it is scheduled. Use a timestamp for appointments
1144 or any reminders you want to show up only on a particular day.
1146 : ** TODO Item with an active timestamp
1149 Note: items with inactive timestamps (set with C-c ! and marked by
1150 square brackets) will not show up in the agenda at all.
1152 ** Can I add files recursively to my list of agenda files?
1153 #<<set-agenda-files-recursively>>
1155 Yes, you can use the library "find-lisp."
1157 : (load-library "find-lisp")
1158 : (setq org-agenda-files (find-lisp-find-files "~/org" "\.org$"))
1160 This will add all files ending in =org= in the directory "~/org"
1161 and all of its subdirectories to your list of agenda files.
1163 See [[http://thread.gmane.org/gmane.emacs.orgmode/8992][this thread]] on the mailing list for more information.
1165 * Appointments/Diary
1166 ** Is it possible to include entries from org-mode files into my emacs diary?
1167 #<<include-entries-from-org-mode-files-into-emacs-diary>>
1169 Since the org-mode agenda is much more powerful and can contain the
1170 diary, you should think twice before deciding to do this. If you
1171 insist, however, integrating Org-mode information into the diary is
1172 possible. You need to turn on /fancy diary display/ by setting in
1175 : (add-hook 'diary-display-hook 'fancy-diary-display)
1177 Then include the following line into your ~/diary file, in
1178 order to get the entries from all files listed in the variable
1183 You may also select specific files with
1185 : &%%(org-diary) ~/path/to/some/org-file.org
1186 : &%%(org-diary) ~/path/to/another/org-file.org
1188 If you now launch the calendar and press @<tt>d@</tt> to display a
1189 diary, the headlines of entries containing a timestamp, date range,
1190 schedule, or deadline referring to the selected date will be listed.
1191 Just like Org-mode's agenda view, the diary for /today/ contains
1192 additional entries for overdue deadlines and scheduled items. See
1193 also the documentation of the =org-diary= function. Under XEmacs, it
1194 is not possible to jump back from the diary to the org, this works
1195 only in the agenda buffer.
1196 ** I want to add my Org scheduled/deadlined entries in my diary!
1197 #<<add-Org-scheduled/deadlined-entries-to-diary!>>
1199 Put this in your ~/.diary:
1201 : &%%(org-diary :scheduled :timestamp :deadline)
1203 ** How can I set up automatic reminders based on Org information?
1204 #<<automatic-reminders>>
1206 See [[http://article.gmane.org/gmane.emacs.orgmode/5271][this post]] by N. Dokos on the list.
1207 ** How can I make =appt= notice my Org appointments?
1208 #<<appt-notice-my-Org-appointments>>
1210 : M-x org-agenda-to-appt RET
1212 ** How can I shedule an weekly appointment that lasts only until a certain date?
1213 #<<diary-sexp-in-org-files>>
1215 Org-mode's active timestamps work very well for scheduling individual
1216 or recurring appointments, such as:
1218 : * 8:00am Dentist appointment <2009-01-16 Fri>
1222 : * Weekly meeting with boss
1223 : <2009-01-20 Tue 14:00 +1w>
1225 Sometimes, however, you need to set up more complicated recurring
1226 appointments. Org-mode has built-in support for many of [[http://www.gnu.org/software/emacs/manual/html_node/emacs/Sexp-Diary-Entries.html][the powerful
1227 sexp entries]] that work in [[http://www.gnu.org/software/emacs/manual/html_node/emacs/Diary.html#Diary][Emacs diary]]. Let's say, for instance, that
1228 you teach a class that meets every Monday evening between February 16
1229 and April 20, 2009. The way to enter this an org-mode file is:
1231 : ** Class 7:00pm-9:00pm
1232 : <%%(and (= 1 (calendar-day-of-week date)) (diary-block 2 16 2009 4 20 2009))>
1234 The expression above designates all Mondays (1) that fall between
1235 February 16 and April 20.
1237 For more ideas on how to create such expressions, see [[http://www.emacswiki.org/cgi-bin/wiki/DiaryMode][this page on the
1241 ** Can I get TODO items exported to HTML as lists, rather than as headlines?
1242 #<<export-TODO-items-as-lists>>
1244 If you plan to use ASCII or HTML export, make sure things you want to
1245 be exported as item lists are level 4 at least, even if that does
1246 mean there is a level jump. For example:
1248 : * Todays top priorities
1249 : **** TODO write a letter to xyz
1250 : **** TODO Finish the paper
1251 : **** Pick up kids at the school
1253 Alternatively, if you need a specific value for the heading/item
1254 transition in a particular file, use the =#+OPTIONS= line to
1255 configure the H switch.
1257 : #+OPTIONS: H:2; ...
1259 ** Can I export only a single subtree?
1260 #<<export-single-subtree>>
1262 If you want to export a subtree, mark the subtree as region and then
1263 export. Marking can be done with =C-c @ C-x C-x=, for example.
1265 ** How can I get Mac OSX 10.3 iCal to import my Org-exported .ics files?
1266 #<<iCal-import-ics-files-old>>
1268 When using iCal under Apple MacOS X Tiger, you can create a new
1269 calendar /OrgMode/ (the default name for the calendar created by =C-c
1270 C-e c=, see the variables =org-icalendar-combined-name= and
1271 =org-combined-agenda-icalendar-file=). Then set Org-mode to
1272 overwrite the corresponding file /~/Library/Calendars/OrgMode.ics/.
1273 You may even use AppleScript to make iCal re-read the calendar files
1274 each time a new version of /OrgMode.ics/ is produced. Here is the
1275 setup needed for this:
1277 : (setq org-combined-agenda-icalendar-file
1278 : "~/Library/Calendars/OrgMode.ics")
1279 : (add-hook 'org-after-save-iCalendar-file-hook
1282 : "osascript -e 'tell application \"iCal\" to reload calendars'")))
1284 ** How can I get Mac OSX 10.4 or later iCal to import my Org-exported .ics files?
1285 #<<iCal-import-ics-files-new>>
1287 For Mac OS X 10.4, you need to write the ics file to
1288 =/Library/WebServer/Documents/= and then subscribe iCalendar to
1289 =http: //localhost/orgmode.ics=
1291 ** How can I remove timestamps and todo keywords from my exported file?
1292 #<<export-options-remove-timestamps>>
1294 You can place an options line at the top of your org file:
1296 : #+OPTIONS: <:nil todo:nil
1298 There is a whole host of export options you can set with an in-buffer
1299 options or via global variables. See [[http://orgmode.org/manual/Export-options.html#Export-options][this section]] of the manual for a
1302 ** How can I preserve faces when I export an agenda from the command line?
1303 #<<preserving-faces-during-batch-export>>
1305 Normally, when you export an org file or an agenda view from within
1306 emacs, htmlize will convert your face definitions to direct color css
1307 styles inlined into each =<span>= object, resulting in an HTML output
1308 that preserves the general look of your Org buffers and agenda views.
1310 Let's say you generate an export from the command line, such as the
1313 : emacs -batch -l ~/.emacs -eval '(org-batch-agenda "e")'
1317 : emacs -batch -l ~/.emacs -eval '(org-publish-all)'
1319 In such an instance, the exported HTML will contain only very basic
1320 color styles. The reason is that when Emacs is run in batch mode, it
1321 does not have a display and therefore only rudimentary face
1322 definitions. If you'd like to use more complex styles, you'll have to
1323 make sure that the export process only assigns classes instead of
1324 direct color values. This can be done by binding the variable
1325 =org-export-htmlize-output-style= to =css= for the duration of the
1326 export, for example with
1328 : emacs -batch -l ~/.emacs
1329 : -eval '(let ((org-export-htmlize-generate-css (quote css)))
1330 : (org-batch-agenda "e"))'
1332 Then you can use a style file to make these classes look any way you
1333 like. To generate face definitions for a CSS file based on any faces
1334 you are currently using in Emacs, you can use the following command:
1336 : M-x org-export-htmlize-generate-css RET
1338 This will generate a =<style>...</style>= section, the content of
1339 which you can add to your style file.
1342 * COMMENT HTML style specifications
1344 (defun org-faq-make-target () "Make hard target for current headline."
1345 (interactive) (if (not (org-on-heading-p)) (error "Not on a
1346 headline")) (let ((h (org-trim (org-get-heading 'no-tags)))) (if
1347 (string-match "[ \t]*\\?\\'" h) (setq h (replace-match "" t t h)))
1348 (while (string-match "[ \t]+" h) (setq h (replace-match "-" t t h)))
1349 (beginning-of-line 2) (insert "#<<" h ">>\n")))
1353 # org-export-html-style: ""
1354 # org-export-html-style-extra: "<link rel=stylesheet href=\"/org.css\" type=\"text/css\" />"