When you visit a file, Emacs chooses a major mode automatically. Normally, it makes the choice based on the file name—for example, files whose names end in ‘.c’ are normally edited in C mode—but sometimes it chooses the major mode based on special text in the file. This special text can also be used to enable buffer-local minor modes.
Here is the exact procedure:
First, Emacs checks whether the file contains file-local mode variables. See Local Variables in Files. If there is a file-local variable that specifies a major mode, then Emacs uses that major mode, ignoring all other criteria. There are several methods to specify a major mode using a file-local variable; the simplest is to put the mode name in the first nonblank line, preceded and followed by ‘-*-’. Other text may appear on the line as well. For example,
tells Emacs to use Lisp mode. Note how the semicolon is used to make Lisp treat this line as a comment. You could equivalently write
; -*- mode: Lisp;-*-
You can also use file-local variables to specify buffer-local minor
modes, by using
eval specifications. For example, this first
nonblank line puts the buffer in Lisp mode and enables Auto-Fill mode:
; -*- mode: Lisp; eval: (auto-fill-mode 1); -*-
Note, however, that it is usually inappropriate to enable minor modes this way, since most minor modes represent individual user preferences. If you personally want to use a minor mode for a particular file type, it is better to enable the minor mode via a major mode hook (see Major Modes).
Second, Emacs checks whether the file’s extension matches an entry
in any directory-local
auto-mode-alist. These are found using
the .dir-locals.el facility (see Per-Directory Local Variables).
Third, if there is no file variable specifying a major mode, Emacs
checks whether the file’s contents begin with ‘#!’. If so, that
indicates that the file can serve as an executable shell command,
which works by running an interpreter named on the file’s first line
(the rest of the file is used as input to the interpreter).
Therefore, Emacs tries to use the interpreter name to choose a mode.
For instance, a file that begins with ‘#!/usr/bin/perl’ is opened
in Perl mode. The variable
the correspondence between interpreter program names and major modes.
When the first line starts with ‘#!’, you usually cannot use the ‘-*-’ feature on the first line, because the system would get confused when running the interpreter. So Emacs looks for ‘-*-’ on the second line in such files as well as on the first line. The same is true for man pages which start with the magic string ‘'\"’ to specify a list of troff preprocessors.
Fourth, Emacs tries to determine the major mode by looking at the
text at the start of the buffer, based on the variable
magic-mode-alist. By default, this variable is
empty list), so Emacs skips this step; however, you can customize it
in your init file (see The Emacs Initialization File). The value should be a list of
elements of the form
(regexp . mode-function)
where regexp is a regular expression (see Syntax of Regular Expressions), and mode-function is a major mode command. If the text at the beginning of the file matches regexp, Emacs chooses the major mode specified by mode-function.
Alternatively, an element of
magic-mode-alist may have the form
(match-function . mode-function)
where match-function is a Lisp function that is called at the
beginning of the buffer; if the function returns non-
set the major mode with mode-function.
Fifth—if Emacs still hasn’t found a suitable major mode—it
looks at the file’s name. The correspondence between file names and
major modes is controlled by the variable
value is a list in which each element has this form,
(regexp . mode-function)
or this form,
(regexp mode-function flag)
For example, one element normally found in the list has the form
(, and it is responsible for selecting C
mode for files whose names end in .c. (Note that ‘\\’ is
needed in Lisp syntax to include a ‘\’ in the string, which must
be used to suppress the special meaning of ‘.’ in regexps.)
"\\.c\\'" . c-mode)
If the element has the form
(regexp mode-function flag) and flag is non-
nil, then after calling
mode-function (if it is non-
nil), Emacs discards the
suffix that matched regexp and searches the list again for
another match. This “recursive extension stripping” is used for
files which have multiple extensions, and the “outer” extension
hides the “inner” one that actually specifies the right mode. For
example, backup files and GPG-encrypted files with .gpg
extension use this feature.
On GNU/Linux and other systems with case-sensitive file names, Emacs
performs a case-sensitive search through
this search fails, it performs a second case-insensitive search
through the alist. To suppress the second search, change the variable
nil. On systems with
case-insensitive file names, such as Microsoft Windows, Emacs performs
a single case-insensitive search through
Finally, if Emacs still hasn’t found a major mode to use, it
compares the text at the start of the buffer to the variable
magic-fallback-mode-alist. This variable works like
magic-mode-alist, described above, except that it is consulted
auto-mode-alist. By default,
magic-fallback-mode-alist contains forms that check for image
files, HTML/XML/SGML files, PostScript files, and Unix style Conf
Once a major mode is found, Emacs does a final check to see if the
mode has been remapped by
major-mode-remap-alist, in which case
it uses the remapped mode instead. This is used when several
different major modes can be used for the same file type, so you can
specify which mode you prefer.
If you have changed the major mode of a buffer, you can return to
the major mode Emacs would have chosen automatically, by typing
M-x normal-mode. This is the same function that
find-file calls to choose the major mode. If the buffer is
visiting a file, this command also processes the file’s ‘-*-’
line and file-local variables list (if any). See Local Variables in Files.
If the buffer doesn’t visit a file, the command processes only the
major mode specification, if any, in the ‘-*-’ line and in the
file-local variables list.
The commands C-x C-w and
set-visited-file-name change to
a new major mode if the new file name implies a mode (see Saving Files).
(C-x C-s does this too, if the buffer wasn’t visiting a file.)
However, this does not happen if the buffer contents specify a major
mode, and certain special major modes do not allow the mode to
change. You can turn off this mode-changing feature by setting