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
11 <a href="/"><img src="http://orgmode.org/img/org-mode-unicorn.png" class="logo-link" /></a>
14 [[file:index.org][{Back to Worg's index}]]
21 Welcome to the Org-mode FAQ.
23 You can navigate the FAQ by clicking on any of the topics in the Table
26 If your browser supports JavaScript, you can...
28 - move through the topics by typing "=n=" (next) and "=p=" (previous).
30 - see an outline view of the FAQ by typing "=m=" or clicking "=toggle
33 - search the FAQ by typing "=s=" (basic search) or "=o=" (occur tree).
35 - see a full list of navigation commands by typing "=?=" or clicking
40 :CUSTOM_ID: What-is-org-mode
42 ** Can I implement a GTD workflow with Org-mode?
44 :CUSTOM_ID: GTD-workflow-with-Org-mode
47 Yes, you can. Check for discussions and pointers [[http://orgmode.org/worg/org-gtd-etc.php][here]].
49 ** What is the difference between Org and TaskPaper?
51 :CUSTOM_ID: Org-and-TaskPaper
54 There is really no difference. Org is as /simple/ as [[http://hogbaysoftware.com/products/taskpaper][TaskPaper]]. It
55 is just that, when using Org within Emacs, it lets you do many things
56 that you wouldn't be able to do with TaskPaper. Yes, TaskPaper is
57 fiddle-proof and people using Emacs tends to like fiddling (which is
58 orthogonal to the idea of using todo-list efficiently), but this is
59 just a matter of discipline and common sense, not one of Org's design.
61 Read [[http://article.gmane.org/gmane.emacs.orgmode/6224][Carsten's enlightening statement]] on this.
62 ** What is the meaning of the Unicorn on Org's website?
67 The Unicorn is the logo of Org-mode because:
69 - Org-mode is the UNICs of ORgaNizers.
71 - Org-mode is an Emacs mode, so it makes sense to use an animal
72 similar or related to the gnu used for GNU Emacs.
74 - Org-mode is meant to show you the way, and an animal with two horns
75 can not do this very well, can it?
77 - Unicorn tears are said to reverse petrification, and wasn't this how
78 we all felt before getting to some degree of time and task
81 - It will take forever to learn everything there is to know about a
84 - A unicorn is a fabulous creature. Org-mode wants to be a fabulous
87 Using a unicorn was originally /Bastien Guerry's/ idea, his friend
88 /Christophe Bataillon/ designed the logo for us, and /Greg Newman/
89 gave it a refresh some time later. Bastien writes why he chose a
93 The first reason is not linked to the animal, but to the sounding of the
94 word "Unicorn" - because Org gives you a /uni/que way of producing files
95 in several format (HTML, LaTeX, etc.)
97 The second reason is that a Unicorn doesn't really exist, it is just
98 something you can dream about, and make others believe it does exist.
99 Just like the perfect organizer.
102 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
103 Suckling]] posted a link showing how to make a simple foldable unicorn
104 (very appropriate for an outlining program!).
106 [[http://article.gmane.org/gmane.emacs.orgmode/11735][Tim Burt]] made a very complicated one which is now a treasured
107 possession of the Org-mode author.
109 - Official logo: [[http://orgmode.org/img/nrocinu2.jpg]]
111 - An [[http://orgmode.org/img/nrocinu4.jpg][alternative version]] from Christophe Bataillon (c):
113 - [[http://article.gmane.org/gmane.emacs.orgmode/14293][Chris Randle]] made a [[http://orgmode.org/img/nrocinu.txt][text version]] using the logo and [[http://glassgiant.com][glassgiant.com]]:
115 - [[http://article.gmane.org/gmane.emacs.orgmode/14362][Stefan Vollmar]] made a [[http://orgmode.org/img/nrocinu.pdf][pdf version]] (here in [[http://orgmode.org/img/nrocinu_pdf.png][png]]) using "a simple
116 threshold technique".
118 - [[http://article.gmane.org/gmane.emacs.orgmode/11735/match%3D][Tim Burt]] made a folded Unicorn to match the spirit of Org - see the
119 whole set of pictures [[http://www.flickr.com/photos/tcburt/sets/72157614543357071/][on his flickr page]].
121 - Are unicorns real? Answer [[http://article.gmane.org/gmane.emacs.orgmode/11687/match%3Drosslaird%2Bunicorn][here]] by Ross Laird.
125 :CUSTOM_ID: Keeping-current
127 ** How do I keep current with Org mode development?
129 :CUSTOM_ID: keeping-current-with-Org-mode-development
132 Org mode is developed in [[http://en.wikipedia.org/wiki/Git_(software)][Git]]. You can keep up-to-date with Org
133 mode developement by cloning Org mode repository and refreshing
134 your copy with latest changes whenever you wish. You only need to
135 use two Git commands (clone and pull.) Here are the steps in
136 brief (please customize locations to suit your setup):
138 1. Select a location to house the Org mode repository (approx. 40
139 MB; includes documentation, compiled elisp files and history
140 going all the way back to v4.12a)
142 : $ mkdir $HOME/elisp && cd $HOME/elisp
144 2. Clone the Org mode Git repository.
146 Recommended approach:
148 : $ git clone git://repo.or.cz/org-mode.git
150 Alternate approach if you are behind a firewall that allows only
151 HTTP (can be quite slow):
153 : $ git clone http://repo.or.cz/r/org-mode.git
155 3. Compile and install Org mode and build documentation.
157 : $ cd org-mode && make && make doc && make install
159 Please note that you can choose to /not/ compile at all and run
160 using source =.el= files only. Compiled files speed things up.
162 4. This is where you configure Org mode with Emacs. Please refer
163 to [[./org-tutorials/index.org][Org tutorials]].
165 5. Keeping up-to-date.
167 Cloning the repository is a one time activity. From this point
168 onwards you only need to /pull/ the latest changes.
170 : $ cd $HOME/elisp/org-mode
174 : $ git pull && make clean && make && make doc && make install
176 6. You should restart org mode to have the changes take effect (if
177 you are not rebooting Emacs.) Also since the intention is to
178 "keep up" with Org mode, you should visit ChangeLog and updated
179 sections of documentation for latest updates (use =git log=.)
181 7. As you use your repository over time it will accumulate loose objects.
182 You can reduce the total size of your git repository with
186 which will consolidate loose git objects into pack files. This
187 reduces the size of the repository and speeds up data access to
190 ** How can I keep local changes and still track Org mode development?
192 :CUSTOM_ID: keeping-local-changes-current-with-Org-mode-development
195 Say you want to make minor changes to the Makefile to reflect your
196 location for =emacs=.
198 Create a local branch for your changes on top of origin/master as
201 : $ git checkout -b local origin/master
202 : $ git config branch.local.rebase true
203 : # Make your changes to the Makefile and create a new commit
205 : $ git commit -m 'My local Makefile configurations'
206 : # Update git to a newer version
209 Now each time you pull new commits from the distribution repository
210 your local commits will be rewound and replayed on top of the new
215 You would normally work on your =local= branch which includes your
216 custom commits; there's no need to switch back to the =master=
221 Here is an example of dealing with conflict resolution during git pull.
223 If you get a conflict during a =git pull= you will need to edit the
224 file with the conflict to fix up the conflicting lines and then tell
225 git that you have resolved the conflict.
227 Conflict resolution goes something like this:
229 1. =git pull= fails with a conflict
231 3. =git add= the file to mark the conflict resolved
232 4. =git rebase --continue=
233 5. lather, rinse, and repeat 2-4 as needed
235 For this example we have the following Makefile:
245 and we need to change the =EMACS=emacs= line to =EMACS=myemacs= to
246 make it work well on our system.
250 - create a local branch for our work
252 : $ git checkout -b local origin/master
253 : $ git config branch.local.rebase true
255 This marks the branch so that all local commits on it are rebased
256 on top of any new commits we get in origin/master during a =git
259 - Make our custom changes
261 Edit the makefile so it looks like this:
271 - Create a commit with our custom changes
273 : $ git commit -m 'My local Makefile configurations'
275 - Later we do a =git pull= but that fails with conflicts.
278 : remote: Counting objects: 5, done.
280 : Patch failed at 0001.
282 : When you have resolved this problem run "git rebase --continue".
283 : If you would prefer to skip this patch, instead run "git rebase --skip".
284 : To restore the original branch and stop rebasing run "git rebase --abort".
286 - Fix the conflict in your favourite editor
288 Conflict markers look like this:
290 : <<<<<<< HEAD:Makefile
294 : >>>>>>> Change emacs location:Makefile
296 This attempted =git pull= caused a conflict. Fire up your
297 favourite editor and fix the conflict in the Makefile. The
298 conflict markers are <<<<<<<<<< , ======= , and >>>>>>>>>>. Fix
299 the Makefile appropriately and delete the conflict markers. You
300 already edited these lines earlier so fixing it should be trivial.
302 In this case we changed =EMACS=emacs= to =EMACS=myemacs= and
303 upstream changed =EMACS=emacs= to =EMACS=emacs22=. Just fix the
304 file and save it by deleting the conflict markers and keeping the
305 code you need (in this case the =EMACS=myemacs= line which we
306 originally modified.)
308 - Mark the file's conflict resolved
312 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.
314 - Continue the rebase operation
316 : $ git rebase --continue
318 If any other conflicts arise you fix them the same way - edit the file, mark the conflict resolved, and continue.
320 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"
322 : $ git rebase --abort
324 ** How can I install an up-to-date version of org-mode without "make" tools?
326 :CUSTOM_ID: installing-org-without-make-tools
329 If you are using org-mode on a computer that lacks developer tools for
330 compiling software, such as [[http://www.gnu.org/software/make/][GNU Make]], you will have to use a
331 *different* installation method than [[http://orgmode.org/manual/Installation.html#Installation][the one outlined in the manual]].
333 Please see [[http://article.gmane.org/gmane.emacs.orgmode/15264][this thread]] on the mailing list for several different ways
334 you can install a recent version of org-mode without using the
335 customary =make clean && make && make install=.
337 The result of that discussion is the file/function found in
338 [[http://orgmode.org/worg/org-hacks.php#compiling-org-without-make]].
345 ** How can I quickly browse all Org options?
347 =M-x org-customize RET=
349 See also [[file:org-tutorials/org-customize.org][Carsten's Org customize tutorial]] and [[file:org-configs/org-customization-guide.org][this customization guide]]
352 ** Can I use the editing features of org-mode in other modes?
354 :CUSTOM_ID: use-editing-features-in-other-modes
357 Not really---but there are a few editing features you can use in
360 - For tables there is =orgtbl-mode= which implements the table
361 editor as a minor mode. (To enable, type =M-x orgtbl-mode=)
362 - For ordered lists there is =orgstuct-mode= which allows for easy
363 list editing as a minor mode. (To enable, type =M-x
366 You can activate these modes automatically by using hooks:
368 : (add-hook 'mail-mode-hook 'turn-on-orgtbl)
369 : (add-hook 'mail-mode-hook 'turn-on-orgstruct)
371 For footnotes, there is the function =org-footnote-action=, which
372 works in non-org buffers. This function is a powerful tool for
373 creating and sorting footnotes. To use it globally, you can add the
374 following keybinding to your =.emacs= file (requires Org 6.17 or
377 : (global-set-key (kbd "C-c f") 'org-footnote-action)
379 For other features you need to switch to Org-mode temporarily, or
380 prepare text in a different buffer.
382 ** Why isn't feature "X" working the way it is described in the manual?
384 :CUSTOM_ID: making-sure-org-mode-is-up-to-date
387 Org-mode develops very quickly. There have been a great many changes,
388 for instance, since the release of Emacs 22, which shipped with
389 version 4.67d of org-mode. (Emacs 23 is expected to ship with version
392 Many of the users on the org-mode mailing list are using either a
393 recent release of org-mode or the
394 [[http://orgmode.org/index.html#sec-3.2][development version of
395 org-mode from the git repository]].
397 If some settings and features aren't working the way you expect, make
398 sure that the version of the manual you are consulting matches the
399 version of org-mode you are using.
401 - You can check which version of org-mode you are using by
402 selection =Org --> Documentation --> Show Version= in the Emacs
405 - The [[http://orgmode.org/manual/index.html][online manual]] at [[http://orgmode.org][orgmode.org]] corresponds to the most recent
408 - 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
409 released with the latest official Gnu Emacs release (Emacs 22 and
410 org-mode 4.67d as of February 2009). Note: compared with the
411 manual at the orgmode.org, the manual at www.gnu.org is
412 considerably out of date.
414 For instructions on how to stay current with org-mode, consult [[keeping-current-with-Org-mode-development][this
415 FAQ]] or follow the instructions on [[http://orgmode.org][the official org-mode site]].
417 ** Can I get the visibility-cycling features in outline-mode and outline-minor-mode?
419 :CUSTOM_ID: use-visibility-cycling-in-outline-mode
422 Yes, these functions are written in a way that they are independent of
423 the outline setup. The following setup provides standard Org-mode
424 functionality in outline-mode on =TAB= and =S-TAB=. For
425 outline-minor-mode, we use =C-TAB= instead of =TAB=,
426 because =TAB= usually has mode-specific tasks.
428 #+BEGIN_SRC emacs-lisp
429 (add-hook 'outline-minor-mode-hook
431 (define-key outline-minor-mode-map [(control tab)] 'org-cycle)
432 (define-key outline-minor-mode-map [(shift tab)] 'org-global-cycle)))
433 (add-hook 'outline-mode-hook
435 (define-key outline-mode-map [(tab)] 'org-cycle)
436 (define-key outline-mode-map [(shift tab)] 'org-global-cycle)))
439 Or check out /outline-magic.el/, which does this and also provides
440 promotion and demotion functionality. /outline-magic.el/ is
441 available at [[http://www.astro.uva.nl/~dominik/Tools/outline-magic.el][Outline Magic]].
443 ** Can I save/restore the visibility state of an org-mode buffer?
447 ** How can I keep track of changes in my Org files?
449 :CUSTOM_ID: track-of-changes-in-Org-files
452 Use git to track the history of the files, use a cronjob to check in
453 changes regularly. Such a setup is described by Bernt Hansen
454 in [[http://article.gmane.org/gmane.emacs.orgmode/6233][this message]] on [[http://dir.gmane.org/gmane.emacs.orgmode][emacs-orgmode]].
456 ** Can I use Org-mode as the default mode for all README files?
458 :CUSTOM_ID: Org-mode-as-default-mode
461 Add the following to your .emacs file:
463 : (add-to-list 'auto-mode-alist '("README$" . org-mode))
465 You can even make it the default mode for any files with unspecified
468 : (setq default-major-mode 'org-mode)
470 ** Can I use ido.el for completing stuff in Org?
472 :CUSTOM_ID: ido-complete
475 Yes, you can. If you are an ido user and ido-mode is active, the
476 following setting will make Org use =ido-completing-read= for most
477 of its completing prompts.
479 : (setq org-completion-use-ido t)
481 ** Should I use one big org file or multiple files?
483 :CUSTOM_ID: how-to-organize-org-mode-files
486 Org-mode is flexible enough to accomodate a variety of organizational
487 and time management schemes. Org's
488 [[http://orgmode.org/manual/Document-Structure.html#Document-Structure][outline
489 cycling and convenient editing and navigation commands]] make it
490 possible to maintain all of your projects and notes in a single file.
491 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
492 notes and todos]], also make it a delight to maintain a private "wiki"
493 consisting of multiple files.
495 No matter how you organize your org files, org-mode's agenda commands
496 make it easy to search all your notes and gather together crucial data
499 Moreover, several org-mode settings can be configured either globally
500 in your =.emacs= file or locally (per file or per outline tree). See
501 the [[http://orgmode.org/manual/index.html#Top][manual]] for more details. For an example of local customizations
502 see [[limit-agenda-with-category-match][this FAQ]].
504 Here are a few ideas for organizing org-mode files:
506 - A single file for all your projects and notes.
507 - One file per project.
508 - One file per client.
509 - One file per area of responsibility or type of work (e.g.,
510 household, health, work, etc.).
511 - One file for projects, one for appointments, one for reference
512 material, one for someday/maybe items, etc.
513 - A wiki of hyperlinked files that grows and adapts to meet your
516 For more ideas, see some of the links on the [[file:org-tutorials/index.org][org-tutorial index]] or
517 [[file:org-gtd-etc.org][this page on org-mode and GTD]].
519 ** Why doesn't C-c a call the agenda? Why don't some org keybindings work?
521 :CUSTOM_ID: setting-global-keybindings
524 Org-mode has a few global keybindings that the user must set
525 explicitly in an =.emacs= file. These keybindings include the
526 customary shortcut for calling the agenda (=C-c a=). If nothing
527 happens when you type =C-c a=, then make sure that the following lines
528 are in your =.emacs= file:
530 #+BEGIN_SRC emacs-lisp
531 ;; The following lines are always needed. Choose your own keys.
532 (add-to-list 'auto-mode-alist '("\\.org\\'" . org-mode))
533 (global-set-key "\C-cl" 'org-store-link)
534 (global-set-key "\C-ca" 'org-agenda)
535 (global-set-key "\C-cb" 'org-iswitchb)
538 You may, of course, choose whatever keybindings work best for you
539 and do not conflict with other modes.
541 Please see [[http://orgmode.org/manual/Activation.html][this section of the manual]] if you have additional
544 ** Why aren't some of the variables I've customized having an effect?
546 :CUSTOM_ID: load-org-after-setting-variables
549 Some org variables have to be set before org.el is loaded or else they
550 will not work. (An example is the new variable
551 =org-enforce-todo-dependencies=.)
553 To make sure all your variables work you should not use =(require
554 'org)=. Instead use the following setting:
556 : (require 'org-install)
558 You should also make sure that you do not require any other =org-...=
559 files in your =.emacs= file before you have set your org variables,
560 since these will also cause org.el to be loaded. To be safe, load org
561 files *after* you have set your variables.
563 ** Org-mode has a lot of colors? How can I change them?
565 :CUSTOM_ID: customizing-org-faces
568 This is a question that applies to Emacs as a whole, but it comes up
569 quite frequently on the org-mode mailing list, so it is appropriate to
572 If you would like to change the style of a face in org-mode (or any
573 other Emacs mode), simply type =M-x customize-face [RET]= while the
574 cursor is on the color/style you are interested in modifying. You will
575 be given the opportunity to customize all the faces located at that
578 If you would like an overview of all the faces in org-mode, you can
579 type =C-u M-x list-faces-display [RET] org= and you will be shown all
580 the faces defined by org-mode along with an illustration of their
583 Finally, if you would like verbose information about the properties of
584 the text under the cursor, you can type =C-u C-x ==.
586 ** How can I make sure that timestamps appear in English?
588 :CUSTOM_ID: timestamps-and-system-time-locale
591 If your system's locale is not set to English, but you would like the
592 timestamps in your org-mode files to appear in English, you can set
593 the following variable:
595 #+begin_src emacs-lisp
596 (setq system-time-locale "C")
599 * Errors and general problems
603 ** When I try to use Org-mode, I always get the error message =(wrong-type-argument keymapp nil)=
605 :CUSTOM_ID: wrong-type-argument-keymapp
608 This is a conflict with an outdated version of the /allout.el/, see
609 the [[http://orgmode.org/manual/Conflicts.html#Conflicts][Conflicts]] section in the manual
611 ** Org-mode takes over the TAB key. I also want to use YASnippet, is there a way to fix this conflict?
613 :CUSTOM_ID: YASnippet
616 [[http://code.google.com/p/yasnippet/][yasnippet]] is yet another snippet expansion system for Emacs. It is
617 inspired by TextMate's templating syntax.
618 - watch the [[http://www.youtube.com/watch?v=vOj7btx3ATg][video on YouTube]]
619 - see the [[http://yasnippet.googlecode.com/svn/trunk/doc/index.html][intro and tutorial]]
621 *Note*: yasnippet is not compatible with =org-indent-mode= currently
622 there is no known way to use both successfully with =yas/trigger-key=
623 set to =TAB= (or =[tab]= etc...)
625 The way Org-mode binds the =TAB= key (binding to =[tab]= instead of
626 =\t=) overrules yasnippets' access to this key. The following code
629 #+begin_src emacs-lisp
630 (add-hook 'org-mode-hook
632 (org-set-local 'yas/trigger-key [tab])
633 (define-key yas/keymap [tab] 'yas/next-field-group)))
636 If the above code doesn't work (which it may not with later versions
637 of yasnippet). Then try the following
639 #+begin_src emacs-lisp
640 (defun yas/org-very-safe-expand ()
641 (let ((yas/fallback-behavior 'return-nil)) (yas/expand)))
643 (add-hook 'org-mode-hook
645 ;; yasnippet (using the new org-cycle hooks)
646 (make-variable-buffer-local 'yas/trigger-key)
647 (setq yas/trigger-key [tab])
648 (add-to-list 'org-tab-first-hook 'yas/org-very-safe-expand)
649 (define-key yas/keymap [tab] 'yas/next-field)))
652 Rick Moynihan maintains a [[http://github.com/RickMoynihan/yasnippet-org-mode][git repository]] (or [[http://github.com/eschulte/yasnippet-org-mode][Eric's fork of the same]])
653 with YASnippets for Org-mode.
655 ** Org-mode takes over the S-cursor keys. I also want to use CUA-mode, is there a way to fix this conflict?
660 Yes, see the [[http://orgmode.org/manual/Conflicts.html#Conflicts][Conflicts]] section of the manual.
662 ** Org-mode takes over the S-cursor keys. I also want to use windmove.el, is there a way to fix this conflict?
664 :CUSTOM_ID: windmove.el
667 Yes, see the [[http://orgmode.org/manual/Conflicts.html#Conflicts][Conflicts]] section of the manual.
669 ** Org behaves strangely: some keys don't work, some features are missing, my settings have no effect, ...
671 :CUSTOM_ID: loaded-old-org
674 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=.
676 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.
678 You should add your directories to the =load-path= at the beginning:
680 : (add-to-list 'load-path "~/.emacs.d/org-mode/lisp") (require 'org-install)
682 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)=.
684 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.
686 ** Why doesn't org-batch-agenda work under Win32?
688 :CUSTOM_ID: org-batch-agenda-under-win32
691 When I run the example batch files to print my agenda to the console
692 under Win32 I get the failure:
694 : End of file during parsing
696 and no agenda is printed.
698 The problem is the use of single quotes surrounding the eval in the
699 emacs command-line. This gets confused under Win32. All string
700 parameters with spaces must be surrounded in double quotes. This means
701 that double quotes being passed to the eval must be escaped.
703 Therefore, instead of the following:
705 : <path to emacs>\emacs.exe -batch -l ~/_emacs_org \
706 : -eval '(org-batch-agenda "a")'
708 you need to use the following:
710 : <path to emacs>\emacs.exe -batch -l ~/_emacs_org \
711 : -eval "(org-batch-agenda \"a\")"
713 (all on one line, of course).
715 ** Org agenda seems very slow
717 :CUSTOM_ID: slow-agenda
720 If it takes a long time to generate or refresh the agenda, you might
721 want first check which version of org-mode you are using. There have
722 been major optimizations of org-agenda since 6.21b, which was the
723 version of org-mode released with Emacs 23. If you are using 6.21b or
724 earlier (you can check with =M-x org-version=), then you might want to
725 consider upgrading to a more recent version of org-mode.
727 Here are some other ideas for speeding up the agenda:
729 1. Use a one day agenda view (rather than a seven day view).
731 =(setq org-agenda-ndays 1)=
733 2. Archive inactive items to separate files.
735 =C-c C-x C-s= (org-archive-subtree)
737 3. Do not include the global todo list in your agenda view.
739 (setq org-agenda-include-all-todo nil)
741 4. Make sure that your org files are byte-compiled.
743 I.e., make sure there are files ending in .elc in your org
744 installation directory.
746 ** Visual-line-mode doesn't work well with org-mode
748 :CUSTOM_ID: visual-line-mode
751 Visual-line-mode "soft wraps" lines so that the visual edge of the
752 buffer is considered a line break for purposes of navigation, even
753 though there is no line break in reality.
755 In older versions of org-mode, org-beginning-of-line and
756 org-end-of-line do not work well with visual line mode. (The two
757 commands disregard soft line breaks and move to the beginning and end
758 of the hard line break.) A patch was introduces to fix this behavior
761 If you are using an older version of org mode, you can:
763 1. Add a hook to turn off visual line mode.
765 2. Add the following to your =.emacs=:
767 #+begin_src emacs-lisp
769 (add-hook 'org-mode-hook
771 (define-key org-mode-map "\C-a" 'move-beginning-of-line)
772 (define-key org-mode-map "\C-a" 'move-end-of-line)))
780 ** Can I have two windows on the same Org-mode file, with different outline visibilities?
782 :CUSTOM_ID: indirect-buffers
785 You may use /indirect buffers/ which do exactly this. See the
786 documentation on the command =make-indirect-buffer=.
788 Org-mode has built-in commands that allow you create an indirect
789 buffer from a subtree of an outline. To open a subtree in new
790 window, type =C-c C-x b=. Any changes you make in the new window
791 will be saved to the original file, but the visibility of both
792 buffers will remain independent of one another.
794 For multiple indirect buffers from the same file, you must use the
795 prefix =C-u= when creating the second (or third) buffer. Otherwise
796 the new indirect buffer will replace the old.
798 You can also create an independent view of an outline subtree by
799 typing =b= on an item in the agenda.
801 ** Emacs outlines are unreadable. Can I get rid of all those stars?
803 :CUSTOM_ID: Emacs-outlines-are-unreadable
806 See the section [[http://orgmode.org/manual/Clean-view.html#Clean-view][Clean outline view]] in the manual.
807 ** C-k is killing whole subtrees! I lost my work!
809 :CUSTOM_ID: C-k-is-killing-subtrees
812 =(setq org-special-ctrl-k t)= before losing your work.
814 ** Why aren't commands working on regions?
816 :CUSTOM_ID: transient-mark-mode
819 Some org-mode commands, such as M-right and M-left for demoting or
820 promoting headlines (see [[demote-multiple-headlines][this FAQ]]), can be applied to entire regions.
821 These commands, however, will only work on active regions set with
822 [[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
823 Emacs 23. To enable it in earlier versions of emacs, put the following
824 in your =.emacs= file:
826 : (transient-mark-mode 1)
828 Alternatively, you may turn off transient mark mode and use [[http://www.gnu.org/software/emacs/manual/html_node/emacs/Momentary-Mark.html][a
829 momentary mark]] (=C-<SPC> C-<SPC>=).
831 ** Why is a blank line inserted after headlines and list items?
833 :ID: 2463F4D8-F686-4CF3-AA07-08976F8A4972
836 :CUSTOM_ID: blank-line-after-headlines-and-list-items
839 In org-mode, typing =M-RET= at the end of a headline will create a new
840 headline of the same level on a new line. The same is true for plain
841 lists. By default org-mode uses context to determine if a blank line
842 should be inserted after each headline or plain list item when =M-RET=
843 is pressed. For instance, if a there is a blank line before a
844 headline, then typing =M-RET= at the end of the line will insert a
845 blank line before the new headline. For instance, hitting =M-RET=
846 at the end of "Headline Two" below inserts a new headline without a
853 If there is a blank line between Headline One and Headline Two,
854 however, the results will be as follows:
862 If you do not like the default behavior you can change it with the
863 variable =org-blank-before-new-entry=. You can set headings and/or
864 plain lists to auto (the default setting), t (always), or nil (never).
866 ** How can I promote or demote multiple headlines at once?
868 :CUSTOM_ID: demote-multiple-headlines
871 If you have a long list of first level headlines that you'd like to
872 demote to second level headlines, you can select the headlines as a
873 region and then hit =M-<right>= to demote all the headlines at once.
875 Note: =M-S-<right>= will not work on a selected region. Its use is to
876 demote a single subtree (i.e., a headline and all sub-headlines).
878 If M-<right> doesn't seem to work, make sure transient mark mode is
879 enabled. See [[transient-mark-mode][this FAQ]].
881 ** What's the deal with all the ellipses in my org outlines?
883 :CUSTOM_ID: org-ellipses
886 Org-mode uses ellipses to indicate folded (and thus hidden) text. Most
887 commonly, ellispes occur at the end of headings with folded content:
891 Or, for instance, they may indicate closed drawers:
895 Sometimes, as a result of editing and cycling an outline, ellipses may
896 appear in unexpected places. You should *never* delete these ellipses,
897 as you may accidentally delete hidden text. Instead, you can type =C-c
898 C-r= (org-reveal) to display all hidden text in the vicinity. Or you
899 may type =M-x RET show-all= to reveal all text in the org file.
901 If you would prefer a symbol or face for indicating hidden text, you
902 can customize the variable org-ellipses.
904 ** How do I yank a subtree so it's indented according to points' location?
906 :CUSTOM_ID: yank-indent-subtree
909 You can either use =C-c C-w= with a working [[http://orgmode.org/manual/Refiling-notes.html#Refiling-notes][refile-targets]] setup.
911 Or set =org-yank-adjusted-subtrees= to =t= which will adjust the
912 yanked headline's level correctly.
914 Just use =C-k= and =C-y= as you would everywhere else in Emacs.
918 :CUSTOM_ID: Todos-and-Tags
920 ** How can I cycle through the TODO keyword of an entry?
922 :CUSTOM_ID: cycle-TODO-keywords
925 =C-c C-t= or =S-<left/right>= is what you need.
927 ** How do I track state changes for tasks in Org?
929 :CUSTOM_ID: track-state-changes-for-tasks
932 Take a look at the [[http://thread.gmane.org/gmane.emacs.orgmode/6082][post by Bernt Hansen]] for setting up TODO keyword
933 states and logging timestamps for task state changes.
935 ** Can I select the TODO keywords with a tag-like interface?
937 :CUSTOM_ID: select-TODO-keywords-with-tag-like-interface
940 Yes. Use =(setq org-use-fast-todo-selection t)=
942 If you want to set both your todos and your tags using a single
943 interface, then check out the variable
944 =org-fast-tag-selection-include-todo=.
946 See [[http://orgmode.org/manual/Fast-access-to-TODO-states.html][this section of the manual]] for more details.
948 ** How can I quickly set the tag of an entry?
950 :CUSTOM_ID: quickly-set-tag-of-entry
953 Use =C-c C-c= or =C-c C-q= on the headline. =C-c C-q= is useful for
954 setting tabs in a [[http://orgmode.org/manual/Remember.html#Remember][remember]] buffer, since =C-c C-c= is the default
955 keybinding for filing a note from the remember buffer.
957 You can set tags even more quickly by setting one of the character
958 shortcuts for [[http://orgmode.org/manual/Setting-tags.html#Setting-tags][fast tag selection]].
960 To set tag shortcuts for all org buffers, put something like the
961 following in your =.emacs= file (or create the same settings by
962 typing =M-x customize-variable RET org-tag-alist=):
964 : (setq org-tag-alist '(("computer" . ?c) ("office" . ?o) ("home" . ?h)))
966 To set tag shortcuts for a single buffer, put something like the
967 following at the top of your org file:
969 : #+TAGS: computer(c) office(o) home(h)
971 ** How can I change the colors of TODO keywords?
973 You can use the variable org-todo-keyword-faces. Here are some sample
976 #+begin_src emacs-lisp
977 (setq org-todo-keyword-faces
979 ("TODO" . (:foreground "firebrick2" :weight bold))
980 ("WAITING" . (:foreground "olivedrab" :weight bold))
981 ("LATER" . (:foreground "sienna" :weight bold))
982 ("PROJECT" . (:foreground "steelblue" :weight bold))
983 ("DONE" . (:foreground "forestgreen" :weight bold))
984 ("MAYBE" . (:foreground "dimgrey" :weight bold))
985 ("CANCELED" . shadow)
989 If you want to change the color of all active todos or all inactive
992 : M-x customize-face RET org-todo
993 : M-x customize-face RET org-done
995 You can also set values for each of these in your =.emacs= file:
997 : (set-face-foreground 'org-todo "firebrick2")
998 : (set-face-foreground 'org-done "forestgreen")
1002 :CUSTOM_ID: Hyperlinks
1004 ** Why do I have to confirm the execution of each shell/elisp link?
1006 :CUSTOM_ID: confirm-shell/elisp-link
1009 The confirmation is there to protect you from unwantingly execute
1010 potentially dangerous commands. For example, imagine a link
1012 : [[shell:rm -rf ~/*][Google Search]]
1014 In an Org-mode buffer, this command would look like /Google Search/,
1015 but really it would remove your home directory. If you wish, you can
1016 make it easier to respond to the query by setting
1018 : (setq org-confirm-shell-link-function 'y-or-n-p
1019 : org-confirm-elisp-link-function 'y-or-n-p).
1021 Then a single keypress will be enough to confirm those links. It is
1022 also possible to turn off this check entirely, but I strongly
1023 recommend against this. Be warned.
1025 ** Can I use RET or TAB to follow a link?
1027 :CUSTOM_ID: RET-or-TAB-to-follow-link
1032 : (setq org-return-follows-link t)
1033 : (setq org-tab-follows-link t)
1035 ** Can I keep mouse-1 clicks from following a link?
1037 :CUSTOM_ID: mouse-1-following-link
1040 Activating links with =mouse-1= is a new feature in Emacs 22, to make
1041 link behavior similar to other applications like web browsers. If
1042 you hold the mouse button down a bit longer, the cursor will be set
1043 without following the link. If you cannot get used to this behavior,
1044 you can (as in Emacs 21) use =mouse-2= to follow links and turn off
1045 link activation for =mouse-1= with
1047 : (setq org-mouse-1-follows-link nil)
1049 ** How can I get completion of file names when creating a link?
1051 :CUSTOM_ID: completion-of-file-links
1054 You can use org-insert-link with a prefix argument:
1058 You will be greeted with prompt in the minibuffer that allows for file
1059 completion using your preferred Emacs method for finding files.
1063 :CUSTOM_ID: Plain-Lists
1065 ** How can I insert an empty line before each newly inserted headline, but not before each newly inserted plain-list item?
1067 :CUSTOM_ID: empty-line-before-each-new-headline-but-not-item
1070 : (setq org-blank-before-new-entry
1071 : '((heading . t) (plain-list-item . nil))
1073 See also [[id:2463F4D8-F686-4CF3-AA07-08976F8A4972][Why is a blank line inserted after headlines and list items?]].
1075 ** How can I convert itemized lists to enumerated lists?
1077 :CUSTOM_ID: convert-itemized-to-enumerated-lists
1080 You can use =C-c -= or =S-<left>/<right>= to cycle through the various
1081 bullet headlines available for lists: =-, +, *, 1., 1)=.
1083 See [[http://orgmode.org/manual/Plain-lists.html#Plain-lists][this section of the manual]] for more information.
1085 ** How can I convert plain lists to headlines and vice versa?
1087 :CUSTOM_ID: convert-plain-lists-to-headlines
1090 To convert a plain list item or line to a headline, type =C-c *= on
1091 the headline. This will make the line a subheading of the current
1094 To convert a headline to a plain list item, type =C-c -= while the
1095 cursor is on the headline.
1097 To convert a headline to an unadorned line of text, type =C-c *= on
1100 You can use query replace to accomplish the same things, as Bernt
1101 Hansen explains in [[http://article.gmane.org/gmane.emacs.orgmode/10148][this mailing list post]].
1103 ** Is there a good way to create a description list?
1105 :CUSTOM_ID: description-lists
1108 Yes, these are now built-in:
1111 - item1 :: Description of this item 1
1112 - item2 :: Description of this item 2
1113 - item1 :: Description of this item 3
1114 also in multiple lines
1121 ** Can I plot data from a table?
1123 :CUSTOM_ID: plotting-table-data
1126 Yes, you can, using org-plot.el written by James TD Smith and now
1127 bundled with Org. See [[http://orgmode.org/manual/Org-Plot.html#Org-Plot][the manual section about this]].
1129 See also [[file:org-tutorials/org-plot.org][this excellent tutorial]] by Eric Schulte.
1131 ** How can I fill a table column with incremental numbers?
1133 :CUSTOM_ID: fill-table-column-with-incremental-numbers
1136 Here is how: Use a field formula to set the first value in the column:
1148 Then define a column formula in the second field:
1160 After recomputing the table, the column will be filled with
1161 incremental numbers:
1170 ,#+TBLFM: $1=@-1 + 1::@2$1=1
1173 Note that you could use arbitrary starting values and column formulas.
1175 ** Why does my table column get filled with #ERROR?
1177 :CUSTOM_ID: table-column-filled-with-ERROR
1180 Org-mode tried to compute the column from other fields using a
1181 formula stored in the =#+TBLFM:= line just below the table, and
1182 the evaluation of the formula fails. Fix the fields used in the
1183 formula, or fix the formula, or remove it!
1185 ** How can I stop the table editor from creating new lines?
1187 :CUSTOM_ID: table-editor-creates-new-lines
1190 When I am in the last column of a table and just above a horizontal
1191 line in the table, pressing TAB creates a new table line before the
1192 horizontal line. To move to the line below the
1193 horizontal line instead, do this:
1195 Press =down= (to get on the separator line) and then =TAB=.
1196 Or configure the variable
1198 : (setq org-table-tab-jumps-over-hlines t)
1200 ** How can I get table fields starting with "="?
1202 :CUSTOM_ID: table-fields-starting-with-=
1207 : (setq org-table-formula-evaluate-inline nil)
1209 this will no longer happen. You can still use formulas using the
1210 commands @<tt>C-c =@</tt> and @<tt>C-u C-c =@</tt>
1212 ** How can I change the indentation of an entire table without fixing every line by hand?
1214 :CUSTOM_ID: change-indentation-entire-table
1217 The indentation of a table is set by the first line. So just fix the
1218 indentation of the first line and realign with =TAB=.
1220 ** In my huge table the realigning after each TAB takes too long. What can I do?
1222 :CUSTOM_ID: table-realigning-after-TAB-takes-long
1225 Either split the table into several by inserting an empty line every
1226 100 lines or so. Or turn off the automatic re-align with
1228 : (setq org-table-automatic-realign nil)
1230 After this the only way to realign a table is to press =C-c C-c=. It
1231 will no longer happen automatically, removing the corresponding delays
1234 ** Recalculation of my table takes too long. What can I do?
1236 :CUSTOM_ID: Recalculation-of-my-table-takes-too-long
1239 Nothing, really. The spreadsheet in org is mostly done to make
1240 calculations possible, not so much to make them fast. Since Org-mode
1241 is firmly committed to the ASCII format, nothing is stopping you from
1242 editing the table by hand. Therefore, there is no internal
1243 representation of the data. Each time Org-mode starts a computation,
1244 it must scan the table for special lines, find the fields etc. This
1245 is slow. Furthermore, Calc is slow compared to hardware
1246 computations. To make this work with normal editing, recalculation
1247 is not happening automatically, or only for the current line, so that
1248 the long wait for a full table iteration only happens when you ask
1251 So for really complex tables, moving to a "real" spreadsheet may
1252 still be the best option.
1254 That said, there are some ways to optimize things in Org-mode, and I
1255 have been thinking about moving a bit further down this line.
1256 However, for my applications this has so far not been an issue at
1257 all. If you have a good case, you could try to convince me.
1259 ** =S-RET= in a table keeps increasing the copied numbers. How can I stop this?
1261 :CUSTOM_ID: S-RET-in-a-table-increases-copied-numbers
1264 Well, it is /supposed/ to be a feature, to make it easy to create a
1265 column with increasing numbers. If this gets into your way, turn it
1268 : (setq org-org-table-copy-increment nil)
1270 ** When I export tables to html, they don't have borders.
1272 :CUSTOM_ID: table-borders-in-html-export
1275 By default, org mode exports tables without borders.
1277 You can changed this by placing an =#+ATTR_HTML= line before the
1280 : #+ATTR_HTML: border="2" rules="all" frame="all"
1282 See [[http://orgmode.org/manual/Tables-in-HTML-export.html#Tables-in-HTML-export][the manual]] for more details.
1286 :CUSTOM_ID: Footnotes
1288 ** How can I get automatic renumbering of footnotes in org-mode?
1290 :CUSTOM_ID: footnote-auto-adjust
1293 You can add the following line to your .emacs file:
1295 : (setq org-footnote-auto-adjust t)
1297 Or, if you prefer, you can turn this option on locally by placing the
1298 following line at the top of your org file:
1300 : #+STARTUP: fnadjust
1302 When auto-adjust is turned on, footnotes in the file with numerical
1303 labels will be renumbered whenever a new footnote is added. Meanwhile,
1304 all footnotes, including those with custom labels such
1305 =[fn:custom-label ]=, will be sorted in the order of their appearance
1308 This emulates the footnote behavior that many users may be familiar
1309 with from word-processing programs or from the footnote-mode included
1312 If you do not turn on org-footnote-auto-adjust, you sort and/or
1313 renumber footnotes at any time by calling org-footnote-action with a
1316 ** Why isn't auto renumbering of footnotes turned on by default?
1318 :CUSTOM_ID: why-no-default-auto-adjust
1321 Org mode has a very robust footnote mechanism allowing for a variety
1322 of types of footnotes. With some of the following footnote notations,
1323 auto-adjust may be either irrelevant or undesired:
1325 - Automatically numbered
1326 - Footnotes with custom labels
1329 In addition, org mode can be customized to place footnotes either at
1330 the end of a document or at the end of the outline heading in which
1331 they appear. Users who change this setting while editing a document
1332 may be disconcerted to find all of their footnotes rearranged
1335 ** I have auto-fill-mode set and org-mode is inserting unwanted comment markers!
1337 :CUSTOM_ID: auto-fill-and-unwanted-comments
1340 If the following occurs:
1350 Make sure that the variable comment-start is nil.
1354 :CUSTOM_ID: Remember
1356 ** Can I use the remember buffer to clock a customer phone call?
1358 :CUSTOM_ID: use-remember-buffer-to-clock-phone-call
1361 Yes, you can. Take a look at the [[http://thread.gmane.org/gmane.emacs.orgmode/5482][setup described by Bernt Hansen]]
1362 and check out (in the same thread) what Nick Docos had to fix to
1363 make Bernt's set-up work for him.
1364 ** Can I automatically start the clock when opening a remember template?
1366 :CUSTOM_ID: start-clock-when-opening-remember-template
1369 Yes, this is possible. Use the following code and make sure that
1370 after executing it, `my-start-clock-if-needed' is in
1371 `remember-mode-hook' /after/ `org-remember-apply-template'.
1373 : (add-hook 'remember-mode-hook 'my-start-clock-if-needed 'append)
1374 : (defun my-start-clock-if-needed ()
1376 : (goto-char (point-min))
1377 : (when (re-search-forward " *CLOCK-IN *" nil t)
1378 : (replace-match "")
1381 Then, when a template contains the key string CLOCK-IN, the clock
1382 will be started. Starting with Org-mode version 5.20, the clock will
1383 automatically be stopped when storing the remember buffer.
1387 :CUSTOM_ID: Searches
1389 ** Isearch does not find string hidden in links. What can I do?
1391 :CUSTOM_ID: isearch-in-links
1394 M-x =visible-mode= will display the full link, making them searchable.
1396 ** How can I reduce the amount of context shown in sparse trees?
1398 :CUSTOM_ID: context-in-sparse-trees
1401 Take a look at the following variables:
1403 - =org-show-hierarchy-above=
1404 - =org-show-following-headline=
1405 - =org-show-siblings=
1406 - =org-show-entry-blow=
1408 which give command-dependent control over how much context is shown
1409 by a particular operation.
1411 ** How can I combine the results of two calls to =org-occur=?
1413 :CUSTOM_ID: two-calls-to-org-occur
1416 You can construct a regular expression that matches all targets you
1417 want. Alternatively, use a =C-u= prefix with the second and any
1418 further calls to =org-occur= to keep the current visibility and
1419 highlighting in addition to the new ones.
1425 ** How can I change the advanced warning time for deadlines?
1426 ##<<warning-period-for-deadlines>>
1428 Deadline warnings appear in the daily agenda view a specified number
1429 of days before the deadline is due. The default setting is 14 days.
1430 You can change this with the variable =org-deadline-warning-days=.
1431 (See [[http://orgmode.org/manual/Deadlines-and-scheduling.html#Deadlines-and-scheduling][this section]] of the manual.)
1435 : (setq org-deadline-warning-days 30)
1437 would cause warnings for each deadline to appear 30 days in advance.
1439 Naturally, you might not want warnings for all of your deadlines to
1440 appear so far in advance. Thus, you can change the lead time for
1441 individual items as follows:
1443 : * TODO Get a gift for the party
1444 : DEADLINE: <2009-01-16 Fri -2d>
1446 The "-2d" above changes the lead time for this deadline warning to two
1447 days in advance. You can also use "w" for weeks and "m" for months.
1448 ** How can I postpone a task until a certain date?
1450 :CUSTOM_ID: deferring-tasks
1453 The easiest way to postpone a task is to schedule it in the future.
1454 For instance, typing =C-c C-s +2w= on a headline will push a task two
1455 weeks into the future, so that it won't show up on the daily agenda
1456 until two weeks from now.
1458 If you'd like to prevent the task from showing up on your global todo
1459 list, you have a couple of options.
1461 1. You can set the variable =org-agenda-todo-ignore-scheduled= to =t=.
1462 This will exclude any scheduled items from your global list of
1463 active todos (=C-c a t=). (The variable
1464 =org-agenda-todo-ignore-with-date= will exclude both scheduled and
1465 deadline items from your todo list).
1466 2. You can remove the todo keyword from the item (C-c C-t <SPC>). The
1467 item will still appear on your agenda two weeks from today, but it
1468 won't show up on your todo lists.
1469 ** Can I send myself an email containing tasks or other agenda info?
1471 :CUSTOM_ID: email-containing-tasks-or-other-agenda-info
1474 Yes. See [[http://article.gmane.org/gmane.emacs.orgmode/6112][this thread]] on the list.
1476 ** How can I limit the agenda view to my "work" tasks?
1478 :CUSTOM_ID: limit-agenda-with-tag-filtering
1481 It is often convenient to group org files into separate categories,
1482 such as "home" and "work" (or "personal" and "professional"). One
1483 of the main reasons for such classification is to create agenda
1484 views that are limited by type of work or area of responsibility.
1485 For instance, while at work, one may want to see only professional
1486 tasks; while away from work, one may want to see only personal
1489 One way to categorize files and tasks is to use a "#+FILETAGS"
1490 declaration at the top of each file, such as:
1494 As long as org-use-tag-inheritance is turned on, the filetags will
1495 be inherited by all tasks in the file. A file can have multiple
1496 filetags. And, of course, tags can be added to individual headings.
1498 Tasks can be quickly filtered by tag from within the agenda by
1499 typing "/" and the name of the tag. The full key sequence to filter
1500 for work items in an agenda view would be:
1502 : C-c a a / work [or a tag shortcut]
1504 ** How can I limit the agenda view to a particular category?
1506 :CUSTOM_ID: limit-agenda-with-category-match
1509 Another way to filter agenda views by type of work is to use a
1510 "#+CATEGORY" declaration at the top of each file, such as:
1514 Categories can also be added to individual headings within a file:
1521 All todos belonging to the category "work" can be found a with a
1522 simple tags-todo search:
1526 At the prompt, type:
1530 The same results can be achieved with custom agenda commands, such as:
1532 #+BEGIN_SRC emacs-lisp
1533 (setq org-agenda-custom-commands
1534 '(("h" tags-todo "CATEGORY=\"home\"")
1535 ("w" tags-todo "CATEGORY=\"work\"")
1536 ;; other custom agenda commands here
1540 ** How can include all org files in a directory in my agenda?
1542 :CUSTOM_ID: set-agenda-files-using-wildcards
1545 You can simply include the directory (as one of the items) in the
1546 value of the variable org-agenda-files:
1548 : (setq org-agenda-files '("/my/special/path/org/"))
1550 There is another way of accomplishing the same end:
1552 : (setq org-agenda-files (file-expand-wildcards "/my/special/path/org/*.org"))
1554 ** Why aren't items disappearing from my agenda once they are marked done?
1556 :CUSTOM_ID: removing-done-items-from-agenda
1559 If items remain on your daily/weekly agenda after they are marked
1560 done, check the configuration of the following variables:
1562 : org-agenda-skip-scheduled-if-done
1563 : org-agenda-skip-deadline-if-done
1564 : org-agenda-skip-timestamp-if-done
1568 : M-x customize-variable RET org-agenda-skip-scheduled-if-done
1570 If this variable is turned off (=nil=), then scheduled items will
1571 remain on the agenda even after they are marked done.
1573 If the variable is turned on (=t=), then scheduled items will
1574 disappear from the agenda after they are marked done.
1576 If these settings seem not to behave the way you expect, then make
1577 sure you understand [[scheduled-vs-deadline-vs-timestamp][the
1578 difference between SCHEDULED, DEADLINE, and timestamps]].
1580 ** What is the difference between SCHEDULED, DEADLINE, and plain timestamps?
1582 :CUSTOM_ID: scheduled-vs-deadline-vs-timestamp
1585 1. SCHEDULED items (set with =C-c C-s=) will appear on your agenda on
1586 the day they are scheduled and on every day thereafter until they
1587 are done. Schedule a task if you want to be reminded to do
1588 something beginning on a certain day and until it is done.
1590 : ** TODO Scheduled item
1591 : SCHEDULED: <2009-03-01 Sun>
1593 2. Items with a DEADLINE timestamp (set with =C-c C-d=) appear on your
1594 agenda in advance of the when they are due and remain on your
1595 agenda until they are done. Add a DEADLINE to an item if you want
1596 to make sure to complete it by a certain date. (The variable
1597 org-deadline-warning-days determines how far in advance items with
1598 deadlines will show up in the agenda. See [[warning-period-for-deadlines][this FAQ]] for more
1601 : ** TODO Item with a deadline
1602 : DEADLINE: <2009-01-20 Tue>
1604 3. An active timestamp (set with =C-c .=) will appear on your agenda
1605 only on the day it is scheduled. Use a timestamp for appointments
1606 or any reminders you want to show up only on a particular day.
1608 : ** TODO Item with an active timestamp
1611 Note: items with inactive timestamps (set with C-c ! and marked by
1612 square brackets) will not show up in the agenda at all.
1614 ** Can I add files recursively to my list of agenda files?
1616 :CUSTOM_ID: set-agenda-files-recursively
1619 Yes, you can use the library "find-lisp."
1621 : (load-library "find-lisp")
1622 : (setq org-agenda-files (find-lisp-find-files "~/org" "\.org$"))
1624 This will add all files ending in =org= in the directory "~/org"
1625 and all of its subdirectories to your list of agenda files.
1627 See [[http://thread.gmane.org/gmane.emacs.orgmode/8992][this thread]] on the mailing list for more information.
1629 ** Why does an item appearing at the wrong time of day in my agenda?
1631 :CUSTOM_ID: agenda-wrong-time-of-day
1634 When preparing the agenda view, org-mode scans each relevant headline
1635 for a time designation. This approach is very nice for adding
1636 free-form timestamps to an item for scheduling. Thus, either of the
1637 following work would work to schedule an item at 10:00am:
1640 ,** 10:00am Get dried ice at the magic store
1641 , SCHEDULED: <2009-05-27 Wed>
1645 ,** Get dried ice at the magic store
1646 , SCHEDULED: <2009-05-27 Wed 10:00>
1649 To enable this flexibility, org-mode scans the entire headline for
1650 time of day notation. A potential problem can arise if you use
1651 inactive timestamps in the headline to note when an item was created.
1655 ,** Get dried ice at the magic store [2009-05-26 Tue 12:58]
1656 , SCHEDULED: <2009-05-27 Wed>
1659 Org mode would interpret the time in the inactive timestamp as a
1660 time-of-day indicator and the entry would appear in your agenda at
1663 If you would like to turn off the time-of-day search, you can
1664 configure the variable =org-agenda-search-headline-for-time= (requires
1667 * Appointments/Diary
1669 :CUSTOM_ID: Appointments/Diary
1671 ** Is it possible to include entries from org-mode files into my emacs diary?
1673 :CUSTOM_ID: include-entries-from-org-mode-files-into-emacs-diary
1676 Since the org-mode agenda is much more powerful and can contain the
1677 diary, you should think twice before deciding to do this. If you
1678 insist, however, integrating Org-mode information into the diary is
1679 possible. You need to turn on /fancy diary display/ by setting in
1682 : (add-hook 'diary-display-hook 'diary-fancy-display)
1684 Then include the following line into your ~/diary file, in
1685 order to get the entries from all files listed in the variable
1690 You may also select specific files with
1692 : &%%(org-diary) ~/path/to/some/org-file.org
1693 : &%%(org-diary) ~/path/to/another/org-file.org
1695 If you now launch the calendar and press @<tt>d@</tt> to display a
1696 diary, the headlines of entries containing a timestamp, date range,
1697 schedule, or deadline referring to the selected date will be listed.
1698 Just like Org-mode's agenda view, the diary for /today/ contains
1699 additional entries for overdue deadlines and scheduled items. See
1700 also the documentation of the =org-diary= function. Under XEmacs, it
1701 is not possible to jump back from the diary to the org, this works
1702 only in the agenda buffer.
1703 ** I want to add my Org scheduled/deadlined entries in my diary!
1705 :CUSTOM_ID: add-Org-scheduled/deadlined-entries-to-diary!
1708 Put this in your ~/.diary:
1710 : &%%(org-diary :scheduled :timestamp :deadline)
1712 ** How can I set up automatic reminders based on Org information?
1714 :CUSTOM_ID: automatic-reminders
1717 See [[http://article.gmane.org/gmane.emacs.orgmode/5271][this post]] by N. Dokos on the list.
1718 ** How can I make =appt= notice my Org appointments?
1720 :CUSTOM_ID: appt-notice-my-Org-appointments
1723 : M-x org-agenda-to-appt RET
1725 ** How can I shedule an weekly appointment that lasts only until a certain date?
1727 :CUSTOM_ID: diary-sexp-in-org-files
1730 Org-mode's active timestamps work very well for scheduling individual
1731 or recurring appointments, such as:
1733 : * 8:00am Dentist appointment <2009-01-16 Fri>
1737 : * Weekly meeting with boss
1738 : <2009-01-20 Tue 14:00 +1w>
1740 Sometimes, however, you need to set up more complicated recurring
1741 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
1742 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
1743 you teach a class that meets every Monday evening between February 16
1744 and April 20, 2009. The way to enter this an org-mode file is:
1746 : ** Class 7:00pm-9:00pm
1747 : <%%(and (= 1 (calendar-day-of-week date)) (diary-block 2 16 2009 4 20 2009))>
1749 The expression above designates all Mondays (1) that fall between
1750 February 16 and April 20.
1752 For more ideas on how to create such expressions, see [[http://www.emacswiki.org/cgi-bin/wiki/DiaryMode][this page on the
1755 ** How can I set an event to occur every day except saturday and sunday?
1761 SCHEDULED: <%%(memq (calendar-day-of-week date) '(1 2 3 4 5))>
1768 ** Can I get TODO items exported to HTML as lists, rather than as headlines?
1770 :CUSTOM_ID: export-TODO-items-as-lists
1773 If you plan to use ASCII or HTML export, make sure things you want to
1774 be exported as item lists are level 4 at least, even if that does
1775 mean there is a level jump. For example:
1777 : * Todays top priorities
1778 : **** TODO write a letter to xyz
1779 : **** TODO Finish the paper
1780 : **** Pick up kids at the school
1782 Alternatively, if you need a specific value for the heading/item
1783 transition in a particular file, use the =#+OPTIONS= line to
1784 configure the H switch.
1786 : #+OPTIONS: H:2; ...
1788 ** Can I export only a single subtree?
1790 :CUSTOM_ID: export-single-subtree
1793 If you want to export a subtree, mark the subtree as region and then
1794 export. Marking can be done with =C-c @ C-x C-x=, for example.
1796 ** How can I tell my calendar web application about appointments in my agenda files?
1798 Here is what you need to do:
1800 1. a script that calls Emacs in batch mode and produce a .ics file
1801 2. a script that uploads this .ics file somewhere on the web
1802 3. tell your webapp to fetch this .ics file on the web
1804 Here is the script I use for the first step:
1806 #+begin_src shell-script-mode
1809 /usr/local/bin/emacs --batch --eval \
1810 "(progn (load-file \"~/install/git/org-mode/org.el\") \
1811 (load-file \"~/elisp/config/org-batch-config.el\") \
1812 (setq org-combined-agenda-icalendar-file \"~/org/cal/org.ics\")
1813 (setq org-agenda-files (quote (\"~/org/bzg.org\"))))" \
1814 -f org-export-icalendar-combine-agenda-files
1817 Depending on your configuration, you might change the load sequence.
1819 Here is the script I use for the second step:
1821 #+begin_src shell-script-mode
1823 /usr/bin/rsync -rtv ~/org/org.ics -e ssh me@my_server:/home/me/public_html/
1826 Note: if you want to cron this rsync script, you will need to let
1827 =my_server= to know about your SSH public key. Check [[http://troy.jdmz.net/rsync/index.html][this page]] as a
1830 Now you can cron the two scripts above and your webapp will always be
1831 up to date with your Org agendas.
1833 Also see [[http://orgmode.org/org.html#Exporting-Agenda-Views][Exporting agenda views]] from Org manual.
1835 ** How can I get Mac OSX 10.3 iCal to import my Org-exported .ics files?
1837 :CUSTOM_ID: iCal-import-ics-files-old
1840 When using iCal under Apple MacOS X Tiger, you can create a new
1841 calendar /OrgMode/ (the default name for the calendar created by =C-c
1842 C-e c=, see the variables =org-icalendar-combined-name= and
1843 =org-combined-agenda-icalendar-file=). Then set Org-mode to
1844 overwrite the corresponding file /~/Library/Calendars/OrgMode.ics/.
1845 You may even use AppleScript to make iCal re-read the calendar files
1846 each time a new version of /OrgMode.ics/ is produced. Here is the
1847 setup needed for this:
1849 : (setq org-combined-agenda-icalendar-file
1850 : "~/Library/Calendars/OrgMode.ics")
1851 : (add-hook 'org-after-save-iCalendar-file-hook
1854 : "osascript -e 'tell application \"iCal\" to reload calendars'")))
1856 ** How can I get Mac OSX 10.4 or later iCal to import my Org-exported .ics files?
1858 :CUSTOM_ID: iCal-import-ics-files-new
1861 For Mac OS X 10.4, you need to write the ics file to
1862 =/Library/WebServer/Documents/= and then subscribe iCalendar to
1863 =http: //localhost/orgmode.ics=
1865 ** How can I remove timestamps and todo keywords from my exported file?
1867 :CUSTOM_ID: export-options-remove-timestamps
1870 You can place an options line at the top of your org file:
1872 : #+OPTIONS: <:nil todo:nil
1874 There is a whole host of export options you can set with an in-buffer
1875 options or via global variables. See [[http://orgmode.org/manual/Export-options.html#Export-options][this section]] of the manual for a
1878 ** How can I preserve faces when I export an agenda from the command line?
1880 :CUSTOM_ID: preserving-faces-during-batch-export
1883 Normally, when you export an org file or an agenda view from within
1884 emacs, htmlize will convert your face definitions to direct color css
1885 styles inlined into each =<span>= object, resulting in an HTML output
1886 that preserves the general look of your Org buffers and agenda views.
1888 Let's say you generate an export from the command line, such as the
1891 : emacs -batch -l ~/.emacs -eval '(org-batch-agenda "e")'
1895 : emacs -batch -l ~/.emacs -eval '(org-publish-all)'
1897 In such an instance, the exported HTML will contain only very basic
1898 color styles. The reason is that when Emacs is run in batch mode, it
1899 does not have a display and therefore only rudimentary face
1900 definitions. If you'd like to use more complex styles, you'll have to
1901 make sure that the export process only assigns classes instead of
1902 direct color values. This can be done by binding the variable
1903 =org-export-htmlize-output-style= to =css= for the duration of the
1904 export, for example with
1906 : emacs -batch -l ~/.emacs
1907 : -eval '(let ((org-export-htmlize-generate-css (quote css)))
1908 : (org-batch-agenda "e"))'
1910 Then you can use a style file to make these classes look any way you
1911 like. To generate face definitions for a CSS file based on any faces
1912 you are currently using in Emacs, you can use the following command:
1914 : M-x org-export-htmlize-generate-css RET
1916 This will generate a =<style>...</style>= section, the content of
1917 which you can add to your style file.
1919 ** How can I avoid dark color background when exporting agenda to ps format?
1921 :CUSTOM_ID: avoiding-dark-background-when-exporting-agenda
1924 Add this to your .emacs and evaluate it.
1926 #+BEGIN_SRC emacs-lisp
1927 (setq org-agenda-exporter-settings
1928 '((ps-print-color-p 'black-white)))
1931 ** How can I get colored source code when exporting to LaTeX?
1933 :CUSTOM_ID: fontified_source_code_w_latex
1936 As of Sun Aug 9 2009 the "current" version of Org-mode (see
1937 [[keeping-current-with-Org-mode-development]]) supports exporting source
1938 code to LaTeX using the listings package.
1940 To turn on listing export add the following to your Org-mode
1942 #+begin_src emacs-lisp
1943 ;; requite org-latex so that the following variables are defined
1944 (require 'org-latex)
1946 ;; tell org to use listings
1947 (setq org-export-latex-listings t)
1949 ;; you must include the listings package
1950 (add-to-list 'org-export-latex-packages-alist '("" "listings"))
1952 ;; if you want colored source code then you need to include the color package
1953 (add-to-list 'org-export-latex-packages-alist '("" "color"))
1956 The listings package will now be used to fontify source code in your
1957 LaTeX documents. By default listings will not color any of your
1958 source code. If you would like to set colors for keywords and
1959 comments in your latex documents you can do so using LaTeX directives
1962 \lstset{keywordstyle=\color{blue},
1963 commentstyle=\color{red},
1964 stringstyle=\color{green}
1968 of if you want to get even fancier with your colors you can try
1969 something like the following
1971 \definecolor{keywords}{RGB}{255,0,90}
1972 \definecolor{comments}{RGB}{60,179,113}
1973 \definecolor{fore}{RGB}{249,242,215}
1974 \definecolor{back}{RGB}{51,51,51}
1976 basicstyle=\color{fore},
1977 keywordstyle=\color{keywords},
1978 commentstyle=\color{comments},
1979 backgroundcolor=\color{back}
1983 For more complex listings use cases consult the [[ftp://ftp.tex.ac.uk/tex-archive/macros/latex/contrib/listings/listings.pdf][listings manual]].
1985 ** How can I export to Latex Beamer
1989 The latex [[http://latex-beamer.sourceforge.net/][Beamer Class]] is a useful class for generating slide shows.
1990 The following can be used to export Org-mode documents to LaTeX
1993 Add the following to your Emacs initialization file.
1994 #+begin_src emacs-lisp
1995 (unless (boundp 'org-export-latex-classes)
1996 (setq org-export-latex-classes nil))
1997 (add-to-list 'org-export-latex-classes
1999 "\\documentclass[11pt]{beamer}\n\\usepackage[utf8]{inputenc}\n\\usepackage[T1]{fontenc}\n\\usepackage{hyperref}\n\\usepackage{verbatim}\n"
2000 ("\\section{%s}" . "\\section*{%s}")
2001 ("\\begin{frame}\\frametitle{%s}" "\\end{frame}"
2002 "\\begin{frame}\\frametitle{%s}" "\\end{frame}")))
2006 : #+LaTeX_CLASS: beamer
2007 in the header of your Org-mode document it will automatically export
2008 to the Beamer document class on LaTeX export. With the above
2009 configuration top-level headers will be mapped to sections in the
2010 Beamer document, second-level headers will be mapped to frames, and
2011 lower level headlines will be mapped to itemize objects.
2013 This above is adapted from an [[http://article.gmane.org/gmane.emacs.orgmode/15077/match=beamer+dokos][email by Nick Dokos]], and an [[http://article.gmane.org/gmane.emacs.orgmode/17767/match=beamer+dokos][email by
2014 Thomas Dye]]. For a much more complex Beamer setup see the [[http://article.gmane.org/gmane.emacs.orgmode/17767/match=beamer+dokos][email by
2017 * COMMENT HTML style specifications
2019 #+begin_src emacs-lisp
2020 (defun org-faq-make-target ()
2021 "Make hard target for current headline."
2023 (if (not (org-on-heading-p))
2024 (error "Not on a headline"))
2025 (let ((h (org-trim (org-get-heading 'no-tags))))
2026 (if (string-match "[ \t]*\\?\\'" h)
2027 (setq h (replace-match "" t t h)))
2028 (while (string-match "[ \t]+" h)
2029 (setq h (replace-match "-" t t h)))
2030 (org-entry-put nil "CUSTOM_ID" h)))