8.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 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 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 in columns horizontally in alphabetical order, but this can be changed by changing the completions-format user option. If vertical, sort the completions vertically in columns instead, and if one-column, just use a single column.