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.

When the window showing the completions is selected, either because you customized completion-auto-select or because you switched to it by typing C-x o, the UP and DOWN arrow keys (previous-line-completion and next-line-completion, respectively) move by lines between completion candidates; with a prefix numeric argument, they move that many lines. If completion-auto-wrap is non-nil, these commands will wrap at bottom and top of the candidate list.

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.

When displaying completions, Emacs will normally pop up a new buffer to display the completions. The completions will by default be sorted horizontally, using as many columns as will fit in the window-width, but this can be changed by customizing the completions-format user option. If its value is vertical, Emacs will sort the completions vertically instead, and if it’s one-column, Emacs will use just one column.

The completions-sort user option controls the order in which the completions are sorted in the ‘*Completions*’ buffer. The default is alphabetical, which sorts 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.

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.