1 \input texinfo @c -*-texinfo-*-
2 @setfilename ../../info/ido
3 @settitle Interactive Do
7 This file documents the Ido package for GNU Emacs.
9 Copyright @copyright{} 2013 Free Software Foundation, Inc.
12 Permission is granted to copy, distribute and/or modify this document
13 under the terms of the GNU Free Documentation License, Version 1.3 or
14 any later version published by the Free Software Foundation; with no
15 Invariant Sections, with the Front-Cover texts being ``A GNU Manual'',
16 and with the Back-Cover Texts as in (a) below. A copy of the license
17 is included in the section entitled ``GNU Free Documentation License''.
19 (a) The FSF's Back-Cover Text is: ``You have the freedom to copy and
20 modify this GNU manual.''
24 @dircategory Emacs lisp libraries
26 * Ido: (ido). Interactively do things with buffers and files.
33 @center @titlefont{Interactive Do}
37 @center as distributed with Emacs @value{EMACSVER}
42 @vskip 0pt plus 1filll
56 * Overview:: Basics, activation.
57 * Matching:: Interactivity, matching, scrolling.
58 * Highlighting:: Highlighting of matching items.
59 * Hidden Buffers and Files:: Hidden buffers, files, and directories.
60 * Customization:: Change the Ido functionality.
61 * Misc:: Various other features.
64 * GNU Free Documentation License:: The license for this documentation.
67 * Variable Index:: An entry for each documented variable.
70 --- The Detailed Node Listing ---
74 * Activation:: How to use this package.
78 * Interactive Substring Matching:: Interactivity, matching, scrolling.
79 * Prefix Matching:: Standard completion.
80 * Flexible Matching:: More flexible matching.
81 * Regexp Matching:: Matching using regular expression.
85 * Changing List Order:: Changing the list of files.
86 * Find File At Point:: Make Ido guess the context.
87 * Ignoring:: Ignorance is bliss.
88 * Misc Customization:: Miscellaneous customization for Ido.
92 * All Matching:: Seeing all the matching buffers or files.
93 * Replacement:: Replacement for @code{read-buffer} and @code{read-file-name}.
94 * Other Packages:: Don't want to depend on @code{ido-everywhere}?
104 This document describes a set of features that can interactively do
105 things with buffers and files. All the features are described here
108 The @dfn{Ido} package can let you switch between buffers and visit
109 files and directories with a minimum of keystrokes. It is a superset
110 of Iswitchb, the interactive buffer switching package by Stephen
113 @cindex author of Ido
115 This package was originally written by Kim F. Storm, based on the
116 @file{iswitchb.el} package by Stephen Eglen.
119 * Activation:: How to use this package.
128 This package is distributed with Emacs, so there is no need to install
129 any additional files in order to start using it. To activate, use
133 You may wish to add the following expressions to your initialization
134 file (@pxref{Init File,,The Emacs Initialization File, emacs, GNU
135 Emacs Manual}), if you make frequent use of features from this
143 @c @node Working Directories
144 @c @section Working Directories
145 @c @cindex working directories
152 This section describes features of this package that have to
153 do with various kinds of @emph{matching}: among buffers, files, and directories.
156 * Interactive Substring Matching:: Interactivity, matching, scrolling.
157 * Prefix Matching:: Standard completion.
158 * Flexible Matching:: More flexible matching.
159 * Regexp Matching:: Matching using regular expression.
162 @node Interactive Substring Matching
163 @section Interactive Substring Matching
164 @cindex interactive substring matching
165 @cindex substring, interactive matching
166 @cindex matching, using substring
169 As you type in a substring, the list of buffers or files currently
170 matching the substring are displayed as you type. The list is
171 ordered so that the most recent buffers or files visited come at
172 the start of the list.
174 The buffer or file at the start of the list will be the one visited
175 when you press @key{RET}. By typing more of the substring, the list
176 is narrowed down so that gradually the buffer or file you want will be
177 at the top of the list. Alternatively, you can use @kbd{C-s} and
178 @kbd{C-r} (or the right and left arrow keys) to rotate buffer or file
179 names in the list until the one you want is at the top of the list.
181 Completion is also available so that you can see what is common to
182 all of the matching buffers or files as you type.
184 For example, if there are two buffers called @file{123456} and
185 @file{123}, with @file{123456} the most recent, when using
186 @code{ido-switch-buffer}, you first of all get presented with the list
190 Buffer: @{123456 | 123@}
193 If you then press @kbd{2}:
196 Buffer: 2[3]@{123456 | 123@}
199 The list in @{...@} are the matching buffers, most recent first
200 (buffers visible in the current frame are put at the end of the list
201 by default). At any time you can select the item at the head of the
202 list by pressing @key{RET}. You can also put the first element at the
203 end of the list by pressing @kbd{C-s} or @kbd{<right>}, or bring the
204 last element to the head of the list by pressing @kbd{C-r} or
207 The item in [...] indicates what can be added to your input by
208 pressing @key{TAB} (@code{ido-complete}). In this case, you will get
209 "3" added to your input.
214 Buffer: 23@{123456 | 123@}
217 At this point, you still have two matching buffers. If you want the
218 first buffer in the list, you can simply press @key{RET}. If you want
219 the second in the list, you can press @kbd{C-s} to move it to the top
220 of the list and then press @kbd{RET} to select it.
222 However, if you type @kbd{4}, you'll only have one match left:
228 Since there is only one matching buffer left, it is given in [] and it
229 is shown in the @code{ido-only-match} face (ForestGreen). You can now
230 press @key{TAB} or @key{RET} to go to that buffer.
232 If you want to create a new buffer named @file{234}, you can press
233 @kbd{C-j} (@code{ido-select-text}) instead of @key{TAB} or @key{RET}.
235 If instead, you type @kbd{a}:
238 Buffer: 234a [No match]
241 There are no matching buffers. If you press @key{RET} or @key{TAB},
242 you can be prompted to create a new buffer called @file{234a}.
244 Of course, where this function comes in really useful is when you can
245 specify the buffer using only a few keystrokes. In the above example,
246 the quickest way to get to the @file{123456} file would be just to
247 type @kbd{4} and then @key{RET} (assuming there isn't any newer buffer
248 with @kbd{4} in its name).
250 Likewise, if you use @kbd{C-x C-f} (@code{ido-find-file}), the list of
251 files and directories in the current directory is provided in the same
252 fashion as the buffers above. The files and directories are normally
253 sorted in alphabetical order, but the most recently visited directory
254 is placed first to speed up navigating to directories that you have
257 In addition to scrolling through the list using @kbd{<right>} and
258 @kbd{<left>}, you can use @kbd{<up>} and @kbd{<down>} to quickly
259 scroll the list to the next or previous subdirectory.
261 To go down into a subdirectory, and continue the file selection on
262 the files in that directory, simply move the directory to the head
263 of the list and hit @key{RET}.
265 To go up to the parent directory, delete any partial file name already
266 specified (e.g. using @key{DEL}) and hit @key{DEL}.
268 @c @defun ido-delete-backward-updir
270 @cindex root directory
271 @cindex home directory
272 To go to the root directory (on the current drive), enter two slashes.
273 On MS-DOS or Windows, to select the root of another drive, enter
274 @samp{X:/} where @samp{X} is the drive letter. To go to the home
275 directory, enter @samp{~/}. To enter Dired for this directory, use
278 @c TODO: a new node for ftp hosts
280 You can also visit files on other hosts using the ange-ftp
281 notations @samp{/host:} and @samp{/user@@host:}.
282 @c @defvr {User Option} ido-record-ftp-work-directories
283 @c @defvr {User Option} ido-merge-ftp-work-directories
284 @c @defvr {User Option} ido-cache-ftp-work-directory-time
285 @c @defvr {User Option} ido-slow-ftp-hosts
286 @c @defvr {User Option} ido-slow-ftp-host-regexps
288 You can type @kbd{M-p} and @kbd{M-n} to change to previous/next
289 directories from the history, @kbd{M-s} to search for a file matching
290 your input, and @kbd{M-k} to remove the current directory from the history.
292 If for some reason you cannot specify the proper file using
293 @code{ido-find-file}, you can press @kbd{C-f} to enter the normal
294 @code{find-file}. You can also press @kbd{C-b} to drop into
295 @code{ido-switch-buffer}.
298 @c @findex ido-switch-buffer
299 @c @defun ido-switch-buffer
300 @c This command switch to another buffer interactively.
304 @c @findex ido-find-file
305 @c @defun ido-find-file
306 @c Edit file with name obtained via minibuffer.
312 @c Call Dired the Ido way.
315 @node Prefix Matching
316 @section Prefix Matching
317 @cindex prefix matching
318 @cindex matching, using prefix
319 @cindex standard way of completion
322 The standard way of completion with *nix shells and Emacs is to insert
323 a @dfn{prefix} and then hitting @key{TAB} (or another completion key).
324 Cause of this behavior has become second nature to a lot of Emacs
325 users Ido offers in addition to the default substring matching method
326 (look above) also the prefix matching method. The kind of matching is
327 the only difference to the description of the substring matching
330 You can toggle prefix matching with @kbd{C-p}
331 (@code{ido-toggle-prefix}).
333 For example, if you have two buffers @file{123456} and @file{123} then
334 hitting @kbd{2} does not match because @kbd{2} is not a prefix in any
337 @node Flexible Matching
338 @section Flexible Matching
339 @cindex flexible matching
341 @defvr {User Option} ido-enable-flex-matching
342 If non-@code{nil}, Ido will do flexible string matching. Flexible
343 matching means that if the entered string does not match any item, any
344 item containing the entered characters in the given sequence will
349 If @code{ido-enable-flex-matching} is non-@code{nil}, Ido will do a
350 more flexible matching (unless regexp matching is active) to find
351 possible matches among the available buffer or file names if no
352 matches are found using the normal prefix or substring matching.
354 The flexible matching implies that any item which simply contains all
355 of the entered characters in the specified sequence will match.
357 For example, if you have four files @file{alpha}, @file{beta},
358 @file{gamma}, and @file{delta}, entering @samp{aa} will match
359 @file{alpha} and @file{gamma}, while @samp{ea} matches @file{beta} and
360 @file{delta}. If prefix matching is also active, @samp{aa} only
361 matches @file{alpha}, while @samp{ea} does not match any files.
363 @node Regexp Matching
364 @section Regular Expression Matching
365 @cindex regexp matching
366 @cindex matching, using regular expression
369 There is limited provision for regexp matching within Ido, enabled
370 through @code{ido-enable-regexp} (toggle with @kbd{C-t}). This allows
371 you to type @samp{[ch]$} for example and see all file names ending in
372 @samp{c} or @samp{h}.
374 @defvr {User Option} ido-enable-regexp
375 If the value of this user option is non-@code{nil}, Ido will do regexp
376 matching. The value of this user option can be toggled within
377 ido-mode using @code{ido-toggle-regexp}.
380 @strong{Please notice:} Ido-style completion is inhibited when you
381 enable regexp matching.
384 @chapter Highlighting
388 The highlighting of matching items is controlled via
389 @code{ido-use-faces}. The faces used are @code{ido-first-match},
390 @code{ido-only-match} and @code{ido-subdir}.
392 Coloring of the matching item was suggested by Carsten Dominik.
394 @node Hidden Buffers and Files
395 @chapter Hidden Buffers and Files
396 @cindex hidden buffers and files
398 Normally, Ido does not include hidden buffers (whose name starts with
399 a space) and hidden files and directories (whose name starts with
400 @samp{.}) in the list of possible completions. However, if the
401 substring you enter does not match any of the visible buffers or
402 files, Ido will automatically look for completions among the hidden
405 You can toggle display of the hidden buffers and files with @kbd{C-a}
406 (@code{ido-toggle-ignore}).
408 @c @defun ido-toggle-ignore
411 @chapter Customization
412 @cindex customization
415 You can customize the @code{ido} group to change Ido functionality:
418 M-x customize-group RET ido RET
422 or customize a certain variable:
425 M-x customize-variable RET ido-xxxxx
428 To modify the keybindings, use the @code{ido-setup-hook}. For example:
431 (add-hook 'ido-setup-hook 'ido-my-keys)
433 (defun ido-my-keys ()
434 "Add my keybindings for Ido."
435 (define-key ido-completion-map " " 'ido-next-match))
439 * Changing List Order:: Changing the list of files.
440 * Find File At Point:: Make Ido guess the context.
441 * Ignoring:: Ignorance is bliss.
442 * Misc Customization:: Miscellaneous customization for Ido.
445 @node Changing List Order
446 @section Changing List Order
447 @cindex changing order of the list
450 By default, the list of current files is most recent first,
451 oldest last, with the exception that the files visible in the
452 current frame are put at the end of the list. A hook exists to
453 allow other functions to order the list. For example, if you add:
456 (add-hook 'ido-make-buffer-list-hook 'ido-summary-buffers-to-end)
460 then all files matching "Summary" are moved to the end of the list.
461 (I find this handy for keeping the INBOX Summary and so on out of the
462 way.) It also moves files matching @samp{output\*$} to the end of the
463 list (these are created by AUCTeX when compiling.) Other functions
464 could be made available which alter the list of matching files (either
465 deleting or rearranging elements.)
467 @node Find File At Point
468 @section Find File At Point
469 @cindex find file at point
473 Find File At Point, also known generally as ``ffap'', is an
474 intelligent system for opening files, and URLs.
476 The following expression will make Ido guess the context:
479 (setq ido-use-filename-at-point 'guess)
482 @c @defvr {User Option} ido-use-filename-at-point
483 @c If the value of this user option is non-@code{nil}, ...
486 You can disable URL ffap support by toggling
487 @code{ido-use-url-at-point}.
489 @defvr {User Option} ido-use-url-at-point
490 If the value of this user option is non-@code{nil}, Ido will look for
491 a URL at point. If found, call @code{find-file-at-point} to visit it.
495 @section Ignoring Buffers and Files
497 @cindex regexp, ignore buffers and files
500 Ido is capable of ignoring buffers, directories, files and extensions
501 using regular expression.
503 @defvr {User Option} ido-ignore-buffers
504 This variable takes a list of regular expressions for buffers to
505 ignore in @code{ido-switch-buffer}.
508 @defvr {User Option} ido-ignore-directories
509 This variable takes a list of regular expressions for (sub)directories
510 names to ignore in @code{ido-dired} and @code{ido-find-file}.
513 @defvr {User Option} ido-ignore-files
514 This variable takes a list of regular expressions for files to ignore
515 in @code{ido-find-file}.
518 @defvr {User Option} ido-ignore-unc-host-regexps
519 This variable takes a list of regular expressions matching UNC hosts
520 to ignore. The letter case will be ignored if
521 @code{ido-downcase-unc-hosts} is non-@code{nil}.
524 @c @defvr {User Option} ido-work-directory-list-ignore-regexps
526 To make Ido use @code{completion-ignored-extensions} you need to
530 (setq ido-ignore-extensions t)
533 Now you can customize @code{completion-ignored-extensions} as well.
534 Go ahead and add all the useless object files, backup files, shared
535 library files and other computing flotsam you don’t want Ido to show.
537 @strong{Please notice:} Ido will still complete the ignored elements
538 if it would otherwise not show any other matches. So if you type out
539 the name of an ignored file, Ido will still let you open it just fine.
541 @node Misc Customization
542 @section Miscellaneous Customization
543 @cindex miscellaneous customization for Ido
545 @defvr {User Option} ido-mode
546 This user option determines for which functional group (buffer and
547 files) Ido behavior should be enabled.
550 @defvr {User Option} ido-case-fold
551 If the value of this user option is non-@code{nil}, searching of
552 buffer and file names should ignore case.
555 @defvr {User Option} ido-show-dot-for-dired
556 If the value of this user option is non-@code{nil} , always put
557 @samp{.} as the first item in file name lists. This allows the
558 current directory to be opened immediately with Dired
561 @defvr {User Option} ido-enable-dot-prefix
562 If the value of this user option is non-@code{nil}, Ido will match
563 leading dot as prefix. I.e., hidden files and buffers will match only
564 if you type a dot as first char (even if @code{ido-enable-prefix} is
568 @c @defvr {User Option} ido-confirm-unique-completion
569 @c @defvr {User Option} ido-cannot-complete-command
570 @c @defvr {User Option} ido-record-commands
571 @c @defvr {User Option} ido-max-file-prompt-width
572 @c @defvr {User Option} ido-max-window-height
573 @c @defvr {User Option} ido-enable-last-directory-history
574 @c @defvr {User Option} ido-max-work-directory-list
575 @c @defvr {User Option} ido-enable-tramp-completion
576 @c @defvr {User Option} ido-unc-hosts
577 @c @defvr {User Option} ido-downcase-unc-hosts
578 @c @defvr {User Option} ido-cache-unc-host-shares-time
579 @c @defvr {User Option} ido-max-work-file-list
580 @c @defvr {User Option} ido-work-directory-match-only
581 @c @defvr {User Option} ido-auto-merge-work-directories-length
582 @c @defvr {User Option} ido-auto-merge-delay-time
583 @c @defvr {User Option} ido-auto-merge-inhibit-characters-regexp
584 @c @defvr {User Option} ido-merged-indicator
585 @c @defvr {User Option} ido-max-dir-file-cache
586 @c @defvr {User Option} ido-max-directory-size
587 @c @defvr {User Option} ido-rotate-file-list-default
588 @c @defvr {User Option} ido-enter-matching-directory
589 @c @defvr {User Option} ido-create-new-buffer
590 @c @defvr {User Option} ido-setup-hook
591 @c @defvr {User Option} ido-separator
592 @c @defvr {User Option} ido-decorations
593 @c @defvr {User Option} ido-use-virtual-buffers
594 @c @defvr {User Option} ido-use-faces
595 @c @defvr {User Option} ido-make-file-list-hook
596 @c @defvr {User Option} ido-make-dir-list-hook
597 @c @defvr {User Option} ido-make-buffer-list-hook
598 @c @defvr {User Option} ido-rewrite-file-prompt-functions
599 @c @defvr {User Option} ido-completion-buffer
600 @c @defvr {User Option} ido-completion-buffer-all-completions
601 @c @defvr {User Option} ido-all-frames
602 @c @defvr {User Option} ido-minibuffer-setup-hook
603 @c @defvr {User Option} ido-save-directory-list-file
604 @c @defvr {User Option} ido-read-file-name-as-directory-commands
605 @c @defvr {User Option} ido-read-file-name-non-ido
606 @c @defvr {User Option} ido-before-fallback-functions
607 @c @defvr {User Option} ido-buffer-disable-smart-matches
610 @chapter Miscellaneous
611 @cindex miscellaneous
614 After @kbd{C-x b} (@code{ido-switch-buffer}), the buffer at the head
615 of the list can be killed by pressing @kbd{C-k}. If the buffer needs
616 saving, you will be queried before the buffer is killed.
618 Likewise, after @kbd{C-x C-f}, you can delete (i.e., physically
619 remove) the file at the head of the list with @kbd{C-k}. You will
620 always be asked for confirmation before deleting the file.
622 If you enter @kbd{C-x b} to switch to a buffer visiting a given file,
623 and you find that the file you are after is not in any buffer, you can
624 press @kbd{C-f} to immediately drop into @code{ido-find-file}. And
625 you can switch back to buffer selection with @kbd{C-b}.
627 @c @defun ido-magic-forward-char
628 @c @defun ido-magic-backward-char
630 You can also use Ido in your Emacs Lisp programs:
633 (setq my-pkgs (list "CEDET" "Gnus" "Rcirc" "Tramp" "Org" "all-of-them"))
634 (ido-completing-read "What's your favorite package? " my-pkgs)
638 * All Matching:: Seeing all the matching buffers or files.
639 * Replacement:: Replacement for @code{read-buffer} and @code{read-file-name}.
640 * Other Packages:: Don't want to depend on @code{ido-everywhere}?
644 @section All Matching
646 @cindex seeing all the matching buffers or files
649 If you have many matching files, they may not all fit onto one line of
650 the minibuffer. Normally, the minibuffer window will grow to show you
651 more of the matching files (depending on the value of the variables
652 @code{resize-mini-windows} and @code{max-mini-window-height}). If you
653 want Ido to behave differently from the default minibuffer resizing
654 behavior, set the variable @code{ido-max-window-height}.
656 Also, to improve the responsiveness of Ido, the maximum number of
657 matching items is limited to 12, but you can increase or removed this
658 limit via the @code{ido-max-prospects} user option.
660 @c @defvr {User Option} ido-max-prospects
662 To see a full list of all matching buffers in a separate buffer, hit
663 @kbd{?} or press @key{TAB} when there are no further completions to
664 the substring. Repeated @key{TAB} presses will scroll you through
665 this separate buffer.
671 @code{ido-read-buffer} and @code{ido-read-file-name} have been written
672 to be drop in replacements for the normal buffer and file name reading
673 functions @code{read-buffer} and @code{read-file-name}.
675 To use ido for all buffer and file selections in Emacs, customize the
676 variable @code{ido-everywhere}.
678 @c @defun ido-everywhere
679 @c @defvr {User Option} ido-everywhere
682 @section Other Packages
683 @cindex other packages
684 @cindex used by other packages
687 If you don't want to rely on the @code{ido-everywhere} functionality,
688 @code{ido-read-buffer}, @code{ido-read-file-name}, and
689 @code{ido-read-directory-name} can be used by other packages to read a
690 buffer name, a file name, or a directory name in the @emph{Ido} way.
694 @c * History and Acknowledgments:: How Ido came into being
695 @c @node History and Acknowledgments
696 @c @appendix History and Acknowledgments
698 @node GNU Free Documentation License
699 @appendix GNU Free Documentation License
700 @include doclicense.texi
702 @c @node Function Index
703 @c @unnumbered Function Index
708 @unnumbered Variable Index