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).
90 ** How do I keep current with Org mode development?
91 #<<keeping-current-with-Org-mode-development>>
93 Org mode is developed in [[http://en.wikipedia.org/wiki/Git_(software)][Git]]. You can keep up-to-date with Org
94 mode developement by cloning Org mode repository and refreshing
95 your copy with latest changes whenever you wish. You only need to
96 use two Git commands (clone and pull.) Here are the steps in
97 brief (please customize locations to suit your setup):
99 1. Select a location to house the Org mode repository (approx. 40
100 MB; includes documentation, compiled elisp files and history
101 going all the way back to v4.12a)
103 : $ mkdir $HOME/elisp && cd $HOME/elisp
105 2. Clone the Org mode Git repository.
107 Recommended approach:
109 : $ git clone git://repo.or.cz/org-mode.git
111 Alternate approach if you are behind a firewall that allows only
112 HTTP (can be quite slow):
114 : $ git clone http://repo.or.cz/r/org-mode.git
116 3. Compile and install Org mode and build documentation.
118 : $ cd org-mode && make && make doc && make install
120 Please note that you can choose to /not/ compile at all and run
121 using source =.el= files only. Compiled files speed things up.
123 4. This is where you configure Org mode with Emacs. Please refer
124 to [[./org-tutorials/index.org][Org tutorials]].
126 5. Keeping up-to-date.
128 Cloning the repository is a one time activity. From this point
129 onwards you only need to /pull/ the latest changes.
131 : $ cd $HOME/elisp/org-mode
135 : $ git pull && make clean && make && make doc && make install
137 6. You should restart org mode to have the changes take effect (if
138 you are not rebooting Emacs.) Also since the intention is to
139 "keep up" with Org mode, you should visit ChangeLog and updated
140 sections of documentation for latest updates (use =git log=.)
142 7. As you use your repository over time it will accumulate loose objects.
143 You can reduce the total size of your git repository with
147 which will consolidate loose git objects into pack files. This
148 reduces the size of the repository and speeds up data access to
151 ** How can I keep local changes and still track Org mode development?
152 #<<keeping-local-changes-current-with-Org-mode-development>>
154 Say you want to make minor changes to the Makefile to reflect your
155 location for =emacs=.
157 Create a local branch for your changes on top of origin/master as
160 : $ git checkout -b local origin/master
161 : $ git config branch.local.rebase true
162 : # Make your changes to the Makefile and create a new commit
164 : $ git commit -m 'My local Makefile configurations'
165 : # Update git to a newer version
168 Now each time you pull new commits from the distribution repository
169 your local commits will be rewound and replayed on top of the new
174 You would normally work on your =local= branch which includes your
175 custom commits; there's no need to switch back to the =master=
180 Here is an example of dealing with conflict resultion during git pull.
182 If you get a conflict during a =git pull= you will need to edit the
183 file with the conflict to fix up the conflicting lines and then tell
184 git that you have resolved the conflict.
186 Conflict resolution goes something like this:
188 1. =git pull= fails with a conflict
190 3. =git add= the file to mark the conflict resolved
191 4. =git rebase --continue=
192 5. lather, rinse, and repeat 2-4 as needed
194 For this example we have the following Makefile:
204 and we need to change the =EMACS=emacs= line to =EMACS=myemacs= to
205 make it work well on our system.
209 - create a local branch for our work
211 : $ git checkout -b local origin/master
212 : $ git config branch.local.rebase true
214 This marks the branch so that all local commits on it are rebased
215 on top of any new commits we get in origin/master during a =git
218 - Make our custom changes
220 Edit the makefile so it looks like this:
230 - Create a commit with our custom changes
232 : $ git commit -m 'My local Makefile configurations'
234 - Later we do a =git pull= but that fails with conflicts.
237 : remote: Counting objects: 5, done.
239 : Patch failed at 0001.
241 : When you have resolved this problem run "git rebase --continue".
242 : If you would prefer to skip this patch, instead run "git rebase --skip".
243 : To restore the original branch and stop rebasing run "git rebase --abort".
245 - Fix the conflict in your favourite editor
247 Conflict markers look like this:
249 : <<<<<<< HEAD:Makefile
253 : >>>>>>> Change emacs location:Makefile
255 This attempted =git pull= caused a conflict. Fire up your
256 favourite editor and fix the conflict in the Makefile. The
257 conflict markers are <<<<<<<<<< , ======= , and >>>>>>>>>>. Fix
258 the Makefile appropriately and delete the conflict markers. You
259 already edited these lines earlier so fixing it should be trivial.
261 In this case we changed =EMACS=emacs= to =EMACS=myemacs= and
262 upstream changed =EMACS=emacs= to =EMACS=emacs22=. Just fix the
263 file and save it by deleting the conflict markers and keeping the
264 code you need (in this case the =EMACS=myemacs= line which we
265 originally modified.)
267 - Mark the file's conflict resolved
271 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.
273 - Continue the rebase operation
275 : $ git rebase --continue
277 If any other conflicts arise you fix them the same way - edit the file, mark the conflict resolved, and continue.
279 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"
281 : $ git rebase --abort
284 ** Can I use the editing features of org-mode in other modes?
285 #<<use-editing-features-in-other-modes>>
287 Not really---but there are a few editing features you can use in
290 - For tables there is =orgtbl-mode= which implements the table
291 editor as a minor mode. (To enable, type =M-x orgtbl-mode=)
292 - For ordered lists there is =orgstuct-mode= which allows for easy
293 list editing as a minor mode. (To enable, type =M-x
296 You can activate these modes automatically by using hooks:
298 : (add-hook 'mail-mode-hook 'turn-on-orgtbl)
299 : (add-hook 'mail-mode-hook 'turn-on-orgstruct)
301 For footnotes, there is the function =org-footnote-action=, which
302 works in non-org buffers. This function is a powerful tool for
303 creating and sorting footnotes. To use it globally, you can add the
304 following keybinding to your =.emacs= file (requires Org 6.17 or
307 : (global-set-key (kbd "C-c f") 'org-footnote-action)
309 For other features you need to switch to Org-mode temporarily, or
310 prepare text in a different buffer.
312 ** Why isn't feature "X" working the way it is described in the manual?
313 #<<making-sure-org-mode-is-up-to-date>>
315 Org-mode develops very quickly. There have been a great many changes,
316 for instance, since the release of Emacs 22, which shipped with
317 version 4.67d of org-mode. (Emacs 23 is expected to ship with version
320 Many of the users on the org-mode mailing list are using either a
321 recent release of org-mode or the
322 [[http://orgmode.org/index.html#sec-3.2][development version of
323 org-mode from the git repository]].
325 If some settings and features aren't working the way you expect, make
326 sure that the version of the manual you are consulting matches the
327 version of org-mode you are using.
329 - You can check which version of org-mode you are using by
330 selection =Org --> Documentation --> Show Version= in the Emacs
333 - The [[http://orgmode.org/manual/index.html][online manual]] at [[http://orgmode.org][orgmode.org]] corresponds to the most recent
336 - 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
337 released with the latest official Gnu Emacs release (Emacs 22 and
338 org-mode 4.67d as of February 2009). Note: compared with the
339 manual at the orgmode.org, the manual at www.gnu.org is
340 considerably out of date.
342 For instructions on how to stay current with org-mode, consult [[keeping-current-with-Org-mode-development][this
343 FAQ]] or follow the instructions on [[http://orgmode.org][the official org-mode site]].
345 ** Can I get the visibility-cycling features in outline-mode and outline-minor-mode?
346 #<<use-visibility-cycling-in-outline-mode>>
348 Yes, these functions are written in a way that they are independent of
349 the outline setup. The following setup provides standard Org-mode
350 functionality in outline-mode on =TAB= and =S-TAB=. For
351 outline-minor-mode, we use =C-TAB= instead of =TAB=,
352 because =TAB= usually has mode-specific tasks.
354 #+BEGIN_SRC emacs-lisp
355 (add-hook 'outline-minor-mode-hook
357 (define-key outline-minor-mode-map [(control tab)] 'org-cycle)
358 (define-key outline-minor-mode-map [(shift tab)] 'org-global-cycle)))
359 (add-hook 'outline-mode-hook
361 (define-key outline-mode-map [(tab)] 'org-cycle)
362 (define-key outline-mode-map [(shift tab)] 'org-global-cycle)))
365 Or check out /outline-magic.el/, which does this and also provides
366 promotion and demotion functionality. /outline-magic.el/ is
367 available at [[http://www.astro.uva.nl/~dominik/Tools/OutlineMagic][Outline Magic]].
369 ** How can I keep track of changes in my Org files?
370 #<<track-of-changes-in-Org-files>>
372 Use git to track the history of the files, use a cronjob to check in
373 changes regularly. Such a setup is described by Bernt Hansen
374 in [[http://article.gmane.org/gmane.emacs.orgmode/6233][this message]] on [[http://dir.gmane.org/gmane.emacs.orgmode][emacs-orgmode]].
376 ** Can I use Org-mode as the default mode for all README files?
377 #<<Org-mode-as-default-mode>>
379 Add the following to your .emacs file:
381 : (add-to-list 'auto-mode-alist '("README$" . org-mode))
383 You can even make it the default mode for any files with unspecified
386 : (setq default-major-mode 'org-mode)
388 ** Can I use ido.el for completing stuff in Org?
391 Yes, you can. If you are an ido user and ido-mode is active, the
392 following setting will make Org use =ido-completing-read= for most
393 of its completing prompts.
395 : (setq org-completion-use-ido t)
397 ** Should I use one big org file or multiple files?
398 #<<how-to-organize-org-mode-files>>
400 Org-mode is flexible enough to accomodate a variety of organizational
401 and time management schemes. Org's
402 [[http://orgmode.org/manual/Document-Structure.html#Document-Structure][outline
403 cycling and convenient editing and navigation commands]] make it
404 possible to maintain all of your projects and notes in a single file.
405 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
406 notes and todos]], also make it a delight to maintain a private "wiki"
407 consisting of multiple files.
409 No matter how you organize your org files, org-mode's agenda commands
410 make it easy to search all your notes and gather together crucial data
413 Moreover, several org-mode settings can be configured either globally
414 in your =.emacs= file or locally (per file or per outline tree). See
415 the [[http://orgmode.org/manual/index.html#Top][manual]] for more details. For an example of local customizations
416 see [[limit-agenda-with-category-match][this FAQ]].
418 Here are a few ideas for organizing org-mode files:
420 - A single file for all your projects and notes.
421 - One file per project.
422 - One file per client.
423 - One file per area of responsibility or type of work (e.g.,
424 household, health, work, etc.).
425 - One file for projects, one for appointments, one for reference
426 material, one for someday/maybe items, etc.
427 - A wiki of hyperlinked files that grows and adapts to meet your
430 For more ideas, see some of the links on the [[file:org-tutorials/index.org][org-tutorial index]] or
431 [[file:org-gtd-etc.org][this page on org-mode and GTD]].
433 ** Why doesn't C-c a call the agenda? Why don't some org keybindings work?
434 #<<setting-global-keybindings>>
436 Org-mode has a few global keybindings that the user must set
437 explicitly in an =.emacs= file. These keybindings include the
438 customary shortcut for calling the agenda (=C-c a=). If nothing
439 happens when you type =C-c a=, then make sure that the following lines
440 are in your =.emacs= file:
442 #+BEGIN_SRC emacs-lisp
443 ;; The following lines are always needed. Choose your own keys.
444 (add-to-list 'auto-mode-alist '("\\.org\\'" . org-mode))
445 (global-set-key "\C-cl" 'org-store-link)
446 (global-set-key "\C-ca" 'org-agenda)
447 (global-set-key "\C-cb" 'org-iswitchb)
450 You may, of course, choose whatever keybindings work best for you
451 and do not conflict with other modes.
453 Please see [[http://orgmode.org/manual/Activation.html][this section of the manual]] if you have additional
456 ** Why aren't some of the variables I've customized having an effect?
457 #<<load-org-after-setting-variables>>
459 Some org variables have to be set before org.el is loaded or else they
460 will not work. (An example is the new variable
461 =org-enforce-todo-dependencies=.)
463 To make sure all your variables work you should not use =(require
464 'org)=. Instead use the following setting:
466 : (require 'org-install)
468 You should also make sure that you do not require any other =org-...=
469 files in your =.emacs= file before you have set your org variables,
470 since these will also cause org.el to be loaded. To be safe, load org
471 files *after* you have set your variables.
474 ** When I try to use Org-mode, I always get the error message =(wrong-type-argument keymapp nil)=
475 #<<wrong-type-argument-keymapp>>
477 This is a conflict with an outdated version of the /allout.el/, see
478 the [[http://orgmode.org/manual/Conflicts.html#Conflicts][Conflicts]] section in the manual
480 ** Org-mode takes over the S-cursor keys. I also want to use CUA-mode, is there a way to fix this conflict?
483 Yes, see the [[http://orgmode.org/manual/Conflicts.html#Conflicts][Conflicts]] section of the manual.
485 ** Org-mode takes over the S-cursor keys. I also want to use windmove.el, is there a way to fix this conflict?
488 Yes, see the [[http://orgmode.org/manual/Conflicts.html#Conflicts][Conflicts]] section of the manual.
490 ** Org behaves strangely: some keys don't work, some features are missing, my settings have no effect, ...
493 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=.
495 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.
497 You should add your directories to the =load-path= at the beginning:
499 : (add-to-list 'load-path "~/.emacs.d/org-mode/lisp") (require 'org-install)
501 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)=.
503 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.
505 ** Why doesn't org-batch-agenda work under Win32?
506 #<<org-batch-agenda-under-win32>>
508 When I run the example batch files to print my agenda to the console
509 under Win32 I get the failure:
511 : End of file during parsing
513 and no agenda is printed.
515 The problem is the use of single quotes surrounding the eval in the
516 emacs command-line. This gets confused under Win32. All string
517 parameters with spaces must be surrounded in double quotes. This means
518 that double quotes being passed to the eval must be escaped.
520 Therefore, instead of the following:
522 : <path to emacs>\emacs.exe -batch -l ~/_emacs_org \
523 : -eval '(org-batch-agenda "a")'
525 you need to use the following:
527 : <path to emacs>\emacs.exe -batch -l ~/_emacs_org \
528 : -eval "(org-batch-agenda \"a\")"
530 (all on one line, of course).
533 ** Can I have two windows on the same Org-mode file, with different outline visibilities?
534 #<<indirect-buffers>>
536 You may use /indirect buffers/ which do exactly this. See the
537 documentation on the command =make-indirect-buffer=.
539 Org-mode has built-in commands that allow you create an indirect
540 buffer from a subtree of an outline. To open a subtree in new
541 window, type =C-c C-x b=. Any changes you make in the new window
542 will be saved to the original file, but the visibility of both
543 buffers will remain independent of one another.
545 For multiple indirect buffers from the same file, you must use the
546 prefix =C-u= when creating the second (or third) buffer. Otherwise
547 the new indirect buffer will replace the old.
549 You can also create an independent view of an outline subtree by
550 typing =b= on an item in the agenda.
552 ** Emacs outlines are unreadable. Can I get rid of all those stars?
553 #<<Emacs-outlines-are-unreadable>>
555 See the section [[http://orgmode.org/manual/Clean-view.html#Clean-view][Clean outline view]] in the manual.
556 ** C-k is killing whole subtrees! I lost my work!
557 #<<C-k-is-killing-subtrees>>
559 =(setq org-special-ctrl-k t)= before losing your work.
561 ** Why aren't commands working on regions?
562 #<<transient-mark-mode>>
564 Some org-mode commands, such as M-right and M-left for demoting or
565 promoting headlines (see [[demote-multiple-headlines][this FAQ]]), can be applied to entire regions.
566 These commands, however, will only work on active regions set with
567 [[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
568 Emacs 23. To enable it in earlier versions of emacs, put the following
569 in your =.emacs= file:
571 : (transient-mark-mode 1)
573 Alternatively, you may turn off transient mark mode and use [[http://www.gnu.org/software/emacs/manual/html_node/emacs/Momentary-Mark.html][a
574 momentary mark]] (=C-<SPC> C-<SPC>=).
576 ** How can I promote or demote multiple headlines at once?
577 #<<demote-multiple-headlines>>
579 If you have a long list of first level headlines that you'd like to
580 demote to second level headlines, you can select the headlines as a
581 region and then hit =M-<right>= to demote all the headlines at once.
583 Note: =M-S-<right>= will not work on a selected region. Its use is to
584 demote a single subtree (i.e., a headline and all sub-headlines).
586 If M-<right> doesn't seem to work, make sure transient mark mode is
587 enabled. See [[transient-mark-mode][this FAQ]].
590 ** How can I cycle through the TODO keyword of an entry?
591 #<<cycle-TODO-keywords>>
593 =C-c C-t= or =S-<left/right>= is what you need.
595 ** How do I track state changes for tasks in Org?
596 #<<track-state-changes-for-tasks>>
598 Take a look at the [[http://thread.gmane.org/gmane.emacs.orgmode/6082][post by Bernt Hansen]] for setting up TODO keyword
599 states and logging timestamps for task state changes.
601 ** Can I select the TODO keywords with a tag-like interface?
602 #<<select-TODO-keywords-with-tag-like-interface>>
604 Yes. Use =(setq org-use-fast-todo-selection t)=
606 If you want to set both your todos and your tags using a single
607 interface, then check out the variable
608 =org-fast-tag-selection-include-todo=.
610 See [[http://orgmode.org/manual/Fast-access-to-TODO-states.html][this section of the manual]] for more details.
612 ** How can I quickly set the tag of an entry?
613 #<<quickly-set-tag-of-entry>>
615 Use =C-c C-c= or =C-c C-q= on the headline. =C-c C-q= is useful for
616 setting tabs in a [[http://orgmode.org/manual/Remember.html#Remember][remember]] buffer, since =C-c C-c= is the default
617 keybinding for filing a note from the remember buffer.
619 You can set tags even more quickly by setting one of the character
620 shortcuts for [[http://orgmode.org/manual/Setting-tags.html#Setting-tags][fast tag selection]].
622 To set tag shortcuts for all org buffers, put something like the
623 following in your =.emacs= file (or create the same settings by
624 typing =M-x customize-variable RET org-tag-alist=):
626 : (setq org-tag-alist '(("computer" . ?c) ("office" . ?o) ("home" . ?h)))
628 To set tag shortcuts for a single buffer, put something like the
629 following at the top of your org file:
631 : #+TAGS: computer(c) office(o) home(h)
633 ** How can I change the colors of TODO keywords?
635 You can use the variable org-todo-keyword-faces. Here are some sample
638 #+begin_src emacs-lisp
639 (setq org-todo-keyword-faces
641 ("TODO" . (:foreground "firebrick2" :weight bold))
642 ("WAITING" . (:foreground "olivedrab" :weight bold))
643 ("LATER" . (:foreground "sienna" :weight bold))
644 ("PROJECT" . (:foreground "steelblue" :weight bold))
645 ("DONE" . (:foreground "forestgreen" :weight bold))
646 ("MAYBE" . (:foreground "dimgrey" :weight bold))
647 ("CANCELED" . shadow)
651 If you want to change the color of all active todos or all inactive
654 : M-x customize-face RET org-todo
655 : M-x customize-face RET org-done
657 You can also set values for each of these in your =.emacs= file:
659 : (set-face-foreground 'org-todo "firebrick2")
660 : (set-face-foreground 'org-done "forestgreen")
663 ** Why do I have to confirm the execution of each shell/elisp link?
664 #<<confirm-shell/elisp-link>>
666 The confirmation is there to protect you from unwantingly execute
667 potentially dangerous commands. For example, imagine a link
669 : [[shell:rm -rf ~/*][Google Search]]
671 In an Org-mode buffer, this command would look like /Google Search/,
672 but really it would remove your home directory. If you wish, you can
673 make it easier to respond to the query by setting
675 : (setq org-confirm-shell-link-function 'y-or-n-p
676 : org-confirm-elisp-link-function 'y-or-n-p).
678 Then a single keypress will be enough to confirm those links. It is
679 also possible to turn off this check entirely, but I strongly
680 recommend against this. Be warned.
682 ** Can I use RET or TAB to follow a link?
683 #<<RET-or-TAB-to-follow-link>>
687 : (setq org-return-follows-link t)
688 : (setq org-tab-follows-link t)
690 ** Can I keep mouse-1 clicks from following a link?
691 #<<mouse-1-following-link>>
693 Activating links with =mouse-1= is a new feature in Emacs 22, to make
694 link behavior similar to other applications like web browsers. If
695 you hold the mouse button down a bit longer, the cursor will be set
696 without following the link. If you cannot get used to this behavior,
697 you can (as in Emacs 21) use =mouse-2= to follow links and turn off
698 link activation for =mouse-1= with
700 : (setq org-mouse-1-follows-link nil)
702 ** How can I get completion of file names when creating a link?
703 #<<completion-of-file-links>>
705 You can use org-insert-link with a prefix argument:
709 You will be greeted with prompt in the minibuffer that allows for file
710 completion using your preferred Emacs method for finding files.
712 ** How can I insert an empty line before each newly inserted headline, but not before each newly inserted plain-list item?
713 #<<empty-line-before-each-new-headline-but-not-item>>
715 : (setq org-blank-before-new-entry
716 : '((heading . t) (plain-list-item . nil))
718 ** How can I convert itemized lists to enumerated lists?
719 #<<convert-itemized-to-enumerated-lists>>
721 You can use =C-c -= or =S-<left>/<right>= to cycle through the various
722 bullet headlines available for lists: =-, +, *, 1., 1)=.
724 See [[http://orgmode.org/manual/Plain-lists.html#Plain-lists][this section of the manual]] for more information.
726 ** How can I convert plain lists to headlines and vice versa?
727 #<<convert-plain-lists-to-headlines>>
729 To convert a plain list item or line to a headline, type =C-c *= on
730 the headline. This will make the line a subheading of the current
733 To convert a headline to a plain list item, type =C-c -= while the
734 cursor is on the headline.
736 To convert a headline to an unadorned line of text, type =C-c *= on
739 You can use query replace to accomplish the same things, as Bernt
740 Hansen explains in [[http://article.gmane.org/gmane.emacs.orgmode/10148][this mailing list post]].
742 ** Is there a good way to create a description list?
743 #<<description-lists>>
745 Yes, these are now built-in:
748 - item1 :: Description of this item 1
749 - item2 :: Description of this item 2
750 - item1 :: Description of this item 3
751 also in multiple lines
755 ** Can I plot data from a table?
756 #<<plotting-table-data>>
758 Yes, you can, using org-plot.el written by James TD Smith and now
759 bundled with Org. See [[http://orgmode.org/manual/Org-Plot.html#Org-Plot][the manual section about this]].
761 See also [[file:org-tutorials/org-plot.org][this excellent tutorial]] by Eric Schulte.
763 ** How can I fill a table column with incremental numbers?
764 #<<fill-table-column-with-incremental-numbers>>
766 Here is how: Use a field formula to set the first value in the column:
778 Then define a column formula in the second field:
790 After recomputing the table, the column will be filled with
800 ,#+TBLFM: $1=@-1 + 1::@2$1=1
803 Note that you could use arbitrary starting values and column formulas.
805 ** Why does my table column get filled with #ERROR?
806 #<<table-column-filled-with-ERROR>>
808 Org-mode tried to compute the column from other fields using a
809 formula stored in the =#+TBLFM:= line just below the table, and
810 the evaluation of the formula fails. Fix the fields used in the
811 formula, or fix the formula, or remove it!
813 ** How can I stop the table editor from creating new lines?
814 #<<table-editor-creates-new-lines>>
816 When I am in the last column of a table and just above a horizontal
817 line in the table, pressing TAB creates a new table line before the
818 horizontal line. To move to the line below the
819 horizontal line instead, do this:
821 Press =down= (to get on the separator line) and then =TAB=.
822 Or configure the variable
824 : (setq org-table-tab-jumps-over-hlines t)
826 ** How can I get table fields starting with "="?
827 #<<table-fields-starting-with-=>>
831 : (setq org-table-formula-evaluate-inline nil)
833 this will no longer happen. You can still use formulas using the
834 commands @<tt>C-c =@</tt> and @<tt>C-u C-c =@</tt>
836 ** How can I change the indentation of an entire table without fixing every line by hand?
837 #<<change-indentation-entire-table>>
839 The indentation of a table is set by the first line. So just fix the
840 indentation of the first line and realign with =TAB=.
842 ** In my huge table the realigning after each TAB takes too long. What can I do?
843 #<<table-realigning-after-TAB-takes-long>>
845 Either split the table into several by inserting an empty line every
846 100 lines or so. Or turn off the automatic re-align with
848 : (setq org-table-automatic-realign nil)
850 After this the only way to realign a table is to press =C-c C-c=. It
851 will no longer happen automatically, removing the corresponding delays
854 ** Recalculation of my table takes too long. What can I do?
855 #<<Recalculation-of-my-table-takes-too-long>>
857 Nothing, really. The spreadsheet in org is mostly done to make
858 calculations possible, not so much to make them fast. Since Org-mode
859 is firmly committed to the ASCII format, nothing is stopping you from
860 editing the table by hand. Therefore, there is no internal
861 representation of the data. Each time Org-mode starts a computation,
862 it must scan the table for special lines, find the fields etc. This
863 is slow. Furthermore, Calc is slow compared to hardware
864 computations. To make this work with normal editing, recalculation
865 is not happening automatically, or only for the current line, so that
866 the long wait for a full table iteration only happens when you ask
869 So for really complex tables, moving to a "real" spreadsheet may
870 still be the best option.
872 That said, there are some ways to optimize things in Org-mode, and I
873 have been thinking about moving a bit further down this line.
874 However, for my applications this has so far not been an issue at
875 all. If you have a good case, you could try to convince me.
877 ** =S-RET= in a table keeps increasing the copied numbers. How can I stop this?
878 #<<S-RET-in-a-table-increases-copied-numbers>>
880 Well, it is /supposed/ to be a feature, to make it easy to create a
881 column with increasing numbers. If this gets into your way, turn it
884 : (setq org-org-table-copy-increment nil)
887 ** Can I use the remember buffer to clock a customer phone call?
888 #<<use-remember-buffer-to-clock-phone-call>>
890 Yes, you can. Take a look at the [[http://thread.gmane.org/gmane.emacs.orgmode/5482][setup described by Bernt Hansen]]
891 and check out (in the same thread) what Nick Docos had to fix to
892 make Bernt's set-up work for him.
893 ** Can I automatically start the clock when opening a remember template?
894 #<<start-clock-when-opening-remember-template>>
896 Yes, this is possible. Use the following code and make sure that
897 after executing it, `my-start-clock-if-needed' is in
898 `remember-mode-hook' /after/ `org-remember-apply-template'.
900 : (add-hook 'remember-mode-hook 'my-start-clock-if-needed 'append)
901 : (defun my-start-clock-if-needed ()
903 : (goto-char (point-min))
904 : (when (re-search-forward " *CLOCK-IN *" nil t)
908 Then, when a template contains the key string CLOCK-IN, the clock
909 will be started. Starting with Org-mode version 5.20, the clock will
910 automatically be stopped when storing the remember buffer.
913 ** Isearch does not find string hidden in links. What can I do?
914 #<<isearch-in-links>>
916 M-x =visible-mode= will display the full link, making them searchable.
918 ** How can I reduce the amount of context shown in sparse trees?
919 #<<context-in-sparse-trees>>
921 Take a look at the following variables:
923 - =org-show-hierarchy-above=
924 - =org-show-following-headline=
925 - =org-show-siblings=
926 - =org-show-entry-blow=
928 which give command-dependent control over how much context is shown
929 by a particular operation.
931 ** How can I combine the results of two calls to =org-occur=?
932 #<<two-calls-to-org-occur>>
934 You can construct a regular expression that matches all targets you
935 want. Alternatively, use a =C-u= prefix with the second and any
936 further calls to =org-occur= to keep the current visibility and
937 highlighting in addition to the new ones.
940 ** How can I change the advanced warning time for deadlines?
941 ##<<warning-period-for-deadlines>>
943 Deadline warnings appear in the daily agenda view a specified number
944 of days before the deadline is due. The default setting is 14 days.
945 You can change this with the variable =org-deadline-warning-days=.
946 (See [[http://orgmode.org/manual/Deadlines-and-scheduling.html#Deadlines-and-scheduling][this section]] of the manual.)
950 : (setq org-deadline-warning-days 30)
952 would cause warnings for each deadline to appear 30 days in advance.
954 Naturally, you might not want warnings for all of your deadlines to
955 appear so far in advance. Thus, you can change the lead time for
956 individual items as follows:
958 : * TODO Get a gift for the party
959 : DEADLINE: <2009-01-16 Fri -2d>
961 The "-2d" above changes the lead time for this deadline warning to two
962 days in advance. You can also use "w" for weeks and "m" for months.
963 ** How can I postpone a task until a certain date?
966 The easiest way to postpone a task is to schedule it in the future.
967 For instance, typing =C-c C-s +2w= on a headline will push a task two
968 weeks into the future, so that it won't show up on the daily agenda
969 until two weeks from now.
971 If you'd like to prevent the task from showing up on your global todo
972 list, you have a couple of options.
974 1. You can set the variable =org-agenda-todo-ignore-scheduled= to =t=.
975 This will exclude any scheduled items from your global list of
976 active todos (=C-c a t=). (The variable
977 =org-agenda-todo-ignore-with-date= will exclude both scheduled and
978 deadline items from your todo list).
979 2. You can remove the todo keyword from the item (C-c C-t <SPC>). The
980 item will still appear on your agenda two weeks from today, but it
981 won't show up on your todo lists.
982 ** Can I send myself an email containing tasks or other agenda info?
983 #<<email-containing-tasks-or-other-agenda-info>>
985 Yes. See [[http://article.gmane.org/gmane.emacs.orgmode/6112][this thread]] on the list.
987 ** How can I limit the agenda view to my "work" tasks?
988 #<<limit-agenda-with-tag-filtering>>
990 It is often convenient to group org files into separate categories,
991 such as "home" and "work" (or "personal" and "professional"). One
992 of the main reasons for such classification is to create agenda
993 views that are limited by type of work or area of responsibility.
994 For instance, while at work, one may want to see only professional
995 tasks; while away from work, one may want to see only personal
998 One way to categorize files and tasks is to use a "#+FILETAGS"
999 declaration at the top of each file, such as:
1003 As long as org-use-tag-inheritance is turned on, the filetags will
1004 be inherited by all tasks in the file. A file can have multiple
1005 filetags. And, of course, tags can be added to individual headings.
1007 Tasks can be quickly filtered by tag from within the agenda by
1008 typing "/" and the name of the tag. The full key sequence to filter
1009 for work items in an agenda view would be:
1011 : C-c a a / work [or a tag shortcut]
1013 ** How can I limit the agenda view to a particular category?
1014 #<<limit-agenda-with-category-match>>
1016 Another way to filter agenda views by type of work is to use a
1017 "#+CATEGORY" declaration at the top of each file, such as:
1021 Categories can also be added to individual headings within a file:
1028 All todos belonging to the category "work" can be found a with a
1029 simple tags-todo search:
1033 At the prompt, type:
1037 The same results can be achieved with custom agenda commands, such as:
1039 #+BEGIN_SRC emacs-lisp
1040 (setq org-agenda-custom-commands
1041 '(("h" tags-todo "CATEGORY=\"home\"")
1042 ("w" tags-todo "CATEGORY=\"work\"")
1043 ;; other custom agenda commands here
1047 ** How can include all org files in a directory in my agenda?
1048 #<<set-agenda-files-using-wildcards>>
1050 You can use the file-expand-wildcards function to all files ending in
1051 =org= in a directory to your agenda files list:
1053 : (setq org-agenda-files (file-expand-wildcards "~/org/*.org"))
1055 ** Why aren't items disappearing from my agenda once they are marked done?
1056 #<<removing-done-items-from-agenda>>
1058 If items remain on your daily/weekly agenda after they are marked
1059 done, check the configuration of the following variables:
1061 : org-agenda-skip-scheduled-if-done
1062 : org-agenda-skip-deadline-if-done
1063 : org-agenda-skip-timestamp-if-done
1067 : M-x customize-variable RET org-agenda-skip-scheduled-if-done
1069 If this variable is on (=t=), then scheduled items will remain on the
1070 agenda even after they are marked done.
1072 If the variable is off (=nil=), then scheduled items will disappear
1073 from the agenda after they are marked done.
1075 If these settings seem not to behave the way you expect, then make
1076 sure you understand [[scheduled-vs-deadline-vs-timestamp][the difference between SCHEDULED, DEADLINE, and
1079 ** What is the difference between SCHEDULED, DEADLINE, and plain timestamps?
1080 #<<scheduled-vs-deadline-vs-timestamp>>
1082 1. SCHEDULED items (set with =C-c C-s=) will appear on your agenda on
1083 the day they are scheduled and on every day thereafter until they
1084 are done. Schedule a task if you want to be reminded to do
1085 something beginning on a certain day and until it is done.
1087 : ** TODO Scheduled item
1088 : SCHEDULED: <2009-03-01 Sun>
1090 2. Items with a DEADLINE timestamp (set with =C-c C-d=) appear on your
1091 agenda in advance of the when they are due and remain on your
1092 agenda until they are done. Add a DEADLINE to an item if you want
1093 to make sure to complete it by a certain date. (The variable
1094 org-deadline-warning-days determines how far in advance items with
1095 deadlines will show up in the agenda. See [[warning-period-for-deadlines][this FAQ]] for more
1098 : ** TODO Item with a deadline
1099 : DEADLINE: <2009-01-20 Tue>
1101 3. An active timestamp (set with =C-c .=) will appear on your agenda
1102 only on the day it is scheduled. Use a timestamp for appointments
1103 or any reminders you want to show up only on a particular day.
1105 : ** TODO Item with an active timestamp
1108 Note: items with inactive timestamps (set with C-c ! and marked by
1109 square brackets) will not show up in the agenda at all.
1111 ** Can I add files recursively to my list of agenda files?
1112 #<<set-agenda-files-recursively>>
1114 Yes, you can use the library "find-lisp."
1116 : (load-library "find-lisp")
1117 : (setq org-agenda-files (find-lisp-find-files "~/org" "\.org$"))
1119 This will add all files ending in =org= in the directory "~/org"
1120 and all of its subdirectories to your list of agenda files.
1122 See [[http://thread.gmane.org/gmane.emacs.orgmode/8992][this thread]] on the mailing list for more information.
1124 * Appointments/Diary
1125 ** Is it possible to include entries from org-mode files into my emacs diary?
1126 #<<include-entries-from-org-mode-files-into-emacs-diary>>
1128 Since the org-mode agenda is much more powerful and can contain the
1129 diary, you should think twice before deciding to do this. If you
1130 insist, however, integrating Org-mode information into the diary is
1131 possible. You need to turn on /fancy diary display/ by setting in
1134 : (add-hook 'diary-display-hook 'fancy-diary-display)
1136 Then include the following line into your ~/diary file, in
1137 order to get the entries from all files listed in the variable
1142 You may also select specific files with
1144 : &%%(org-diary) ~/path/to/some/org-file.org
1145 : &%%(org-diary) ~/path/to/another/org-file.org
1147 If you now launch the calendar and press @<tt>d@</tt> to display a
1148 diary, the headlines of entries containing a timestamp, date range,
1149 schedule, or deadline referring to the selected date will be listed.
1150 Just like Org-mode's agenda view, the diary for /today/ contains
1151 additional entries for overdue deadlines and scheduled items. See
1152 also the documentation of the =org-diary= function. Under XEmacs, it
1153 is not possible to jump back from the diary to the org, this works
1154 only in the agenda buffer.
1155 ** I want to add my Org scheduled/deadlined entries in my diary!
1156 #<<add-Org-scheduled/deadlined-entries-to-diary!>>
1158 Put this in your ~/.diary:
1160 : &%%(org-diary :scheduled :timestamp :deadline)
1162 ** How can I set up automatic reminders based on Org information?
1163 #<<automatic-reminders>>
1165 See [[http://article.gmane.org/gmane.emacs.orgmode/5271][this post]] by N. Dokos on the list.
1166 ** How can I make =appt= notice my Org appointments?
1167 #<<appt-notice-my-Org-appointments>>
1169 :M-x org-agenda-to-appt RET
1171 ** How can I shedule an weekly appointment that lasts only until a certain date?
1172 #<<diary-sexp-in-org-files>>
1174 Org-mode's active timestamps work very well for scheduling individual
1175 or recurring appointments, such as:
1177 : * 8:00am Dentist appointment <2009-01-16 Fri>
1181 : * Weekly meeting with boss
1182 : <2009-01-20 Tue 14:00 +1w>
1184 Sometimes, however, you need to set up more complicated recurring
1185 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
1186 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
1187 you teach a class that meets every Monday evening between February 16
1188 and April 20, 2009. The way to enter this an org-mode file is:
1190 : ** Class 7:00pm-9:00pm
1191 : <%%(and (= 1 (calendar-day-of-week date)) (diary-block 2 16 2009 4 20 2009))>
1193 The expression above designates all Mondays (1) that fall between
1194 February 16 and April 20.
1196 For more ideas on how to create such expressions, see [[http://www.emacswiki.org/cgi-bin/wiki/DiaryMode][this page on the
1200 ** Can I get TODO items exported to HTML as lists, rather than as headlines?
1201 #<<export-TODO-items-as-lists>>
1203 If you plan to use ASCII or HTML export, make sure things you want to
1204 be exported as item lists are level 4 at least, even if that does
1205 mean there is a level jump. For example:
1207 : * Todays top priorities
1208 : **** TODO write a letter to xyz
1209 : **** TODO Finish the paper
1210 : **** Pick up kids at the school
1212 Alternatively, if you need a specific value for the heading/item
1213 transition in a particular file, use the =#+OPTIONS= line to
1214 configure the H switch.
1216 : #+OPTIONS: H:2; ...
1218 ** Can I export only a single subtree?
1219 #<<export-single-subtree>>
1221 If you want to export a subtree, mark the subtree as region and then
1222 export. Marking can be done with =C-c @ C-x C-x=, for example.
1224 ** How can I get Mac OSX 10.3 iCal to import my Org-exported .ics files?
1225 #<<iCal-import-ics-files-old>>
1227 When using iCal under Apple MacOS X Tiger, you can create a new
1228 calendar /OrgMode/ (the default name for the calendar created by =C-c
1229 C-e c=, see the variables =org-icalendar-combined-name= and
1230 =org-combined-agenda-icalendar-file=). Then set Org-mode to
1231 overwrite the corresponding file /~/Library/Calendars/OrgMode.ics/.
1232 You may even use AppleScript to make iCal re-read the calendar files
1233 each time a new version of /OrgMode.ics/ is produced. Here is the
1234 setup needed for this:
1236 : (setq org-combined-agenda-icalendar-file
1237 : "~/Library/Calendars/OrgMode.ics")
1238 : (add-hook 'org-after-save-iCalendar-file-hook
1241 : "osascript -e 'tell application \"iCal\" to reload calendars'")))
1243 ** How can I get Mac OSX 10.4 or later iCal to import my Org-exported .ics files?
1244 #<<iCal-import-ics-files-new>>
1246 For Mac OS X 10.4, you need to write the ics file to
1247 =/Library/WebServer/Documents/= and then subscribe iCalendar to
1248 =http: //localhost/orgmode.ics=
1250 ** How can I remove timestamps and todo keywords from my exported file?
1251 #<<export-options-remove-timestamps>>
1253 You can place an options line at the top of your org file:
1255 : #+OPTIONS: <:nil todo:nil
1257 There is a whole host of export options you can set with an in-buffer
1258 options or via global variables. See [[http://orgmode.org/manual/Export-options.html#Export-options][this section]] of the manual for a
1262 * COMMENT HTML style specifications
1264 (defun org-faq-make-target () "Make hard target for current headline."
1265 (interactive) (if (not (org-on-heading-p)) (error "Not on a
1266 headline")) (let ((h (org-trim (org-get-heading 'no-tags)))) (if
1267 (string-match "[ \t]*\\?\\'" h) (setq h (replace-match "" t t h)))
1268 (while (string-match "[ \t]+" h) (setq h (replace-match "-" t t h)))
1269 (beginning-of-line 2) (insert "#<<" h ">>\n")))
1272 #+STYLE: <link rel=\"stylesheet\" href=\"/org.css\" type=\"text/css\" />