---

10.4.5 Completion Options ¶

Case is significant when completing case-sensitive arguments, such as command names. For example, when completing command names, ‘AU’ does not complete to ‘auto-fill-mode’. Case differences are ignored when completing arguments in which case does not matter.

When completing file names, case differences are ignored if the variable read-file-name-completion-ignore-case is non-nil. The default value is nil on systems that have case-sensitive file-names, such as GNU/Linux; it is non-nil on systems that have case-insensitive file-names, such as Microsoft Windows. When completing buffer names, case differences are ignored if the variable read-buffer-completion-ignore-case is non-nil; the default is nil.

When completing file names, Emacs usually omits certain alternatives that are considered unlikely to be chosen, as determined by the list variable completion-ignored-extensions. Each element in the list should be a string; any file name ending in such a string is ignored as a completion alternative. Any element ending in a slash (/) represents a subdirectory name. The standard value of completion-ignored-extensions has several elements including ".o", ".elc", and "~". For example, if a directory contains ‘foo.c’ and ‘foo.elc’, ‘foo’ completes to ‘foo.c’. However, if all possible completions end in otherwise-ignored strings, they are not ignored: in the previous example, ‘foo.e’ completes to ‘foo.elc’. Emacs disregards completion-ignored-extensions when showing completion alternatives in the completion list.

Shell completion is an extended version of filename completion, see Shell Mode Options.

If completion-auto-help is set to nil, the completion commands never display the completion list buffer; you must type ? to display the list. If the value is lazy, Emacs only shows the completion list buffer on the second attempt to complete. In other words, if there is nothing to complete, the first TAB echoes ‘Next char not unique’; the second TAB shows the completion list buffer. If the value is always, the completion list buffer is always shown when completion is attempted.

The display of the completion list buffer after it is shown for the first time is also controlled by completion-auto-help. If the value is t or lazy, the window showing the completions pops down when Emacs is able to complete (and may pop up again if Emacs is again unable to complete after you type some more text); if the value is always, the window pops down only when you exit the completion. The value visible is a hybrid: it behaves like t when it decides whether to pop up the window showing the completion list buffer, and like always when it decides whether to pop it down.

Emacs can optionally select the window showing the completions when it shows that window. To enable this behavior, customize the user option completion-auto-select to t, which changes the behavior of TAB when Emacs pops up the completions: pressing TAB will switch to the completion list buffer, and you can then move to a candidate by cursor motion commands and select it with RET. If the value of completion-auto-select is second-tab, then the first TAB will pop up the completions list buffer, and the second one will switch to it.

If completion-cycle-threshold is non-nil, completion commands can cycle through completion alternatives. Normally, if there is more than one completion alternative for the text in the minibuffer, a completion command completes up to the longest common substring. If you change completion-cycle-threshold to t, the completion command instead completes to the first of those completion alternatives; each subsequent invocation of the completion command replaces that with the next completion alternative, in a cyclic manner. If you give completion-cycle-threshold a numeric value n, completion commands switch to this cycling behavior only when there are n or fewer alternatives.

The user option completions-sort controls the order in which the completions are sorted in the ‘*Completions*’ buffer. With the default value alphabetical, the completions are displayed in alphabetical order. The value nil disables sorting; the value historical sorts alphabetically first, and then rearranges according to the order of the candidates in the minibuffer history. The value can also be a function, which will be called with the list of completions, and should return the list in the desired order.

By default, the ‘*Completions*’ buffer lists the sorted completions horizontally (that is, from left to right across the columns and continuing to the next line below), using as many columns as will fit in the window-width. You can change this by customizing the user option completions-format. If its value is vertical, the ‘*Completions*’ buffer lists the sorted completions vertically (that is, within each column and continuing with the next column to the left), and with the value one-column, all completions appear in a single column.⁵

When point is on the last completion candidate, typing a key that moves point to the next candidate (according to the sorting order of current format) “wraps around” by default, that is, moves point to the first candidate in the completions buffer. Likewise, when point is on the first candidate, typing a key to move to the previous candidate puts point on the last candidate in the buffer. You can suppress this wrapping around by customizing the user option completion-auto-wrap to nil; then typing TAB or n on the last candidate, or typing S-TAB or p on the first candidate, does not move point.

With the arrow keys, the wrapping behavior depends on the completions format in use. In the horizontal format, you can use RIGHT and LEFT, and in the vertical format DOWN and UP, exactly like the format-sensitive keys for moving between completion candidates in the sorting order, and with the same wrapping behavior. In contrast, in the horizontal format DOWN and UP move—and wrap, if wrapping is enabled—only within the current column of completions, and in the vertical format RIGHT and LEFT move (and wrap, if enabled) only within the current line of completions.⁶

When completions-max-height is non-nil, it limits the size of the completions window. It is specified in lines and include mode, header line and a bottom divider, if any. For a more complex control of the Completion window display properties, you can use display-buffer-alist (see Action Alists for Buffer Display in The Emacs Lisp Reference Manual).

The variable completions-header-format is a format spec string to control the informative line shown before the completions list of candidates. If it contains a ‘%s’ construct, that get replaced by the number of completions shown in the completion list buffer. To suppress the display of the heading line, customize this variable to nil. The string that is the value of this variable can have text properties to change the visual appearance of the heading line; some useful properties face or cursor-intangible (see Properties with Special Meanings in The Emacs Lisp Reference Manual).

When completions-highlight-face names a face, the current completion candidate, the one that will be selected by typing RET or clicking the mouse, will be highlighted using that face. The default value of this variable is completions-highlight; the value is nil disables this highlighting. This feature uses the special text property cursor-face.