A file can specify local variable values for use when you edit the file with Emacs. Visiting the file checks for local variable specifications; it automatically makes these variables local to the buffer, and sets them to the values specified in the file.
There are two ways to specify local variable values: in the first line, or with a local variables list. Here's how to specify them in the first line:
-*- mode: modename; var: value; ... -*-
You can specify any number of variables/value pairs in this way, each
pair with a colon and semicolon as shown above.
mode: modename; specifies the major mode; this should come first in the
line. The values are not evaluated; they are used literally.
Here is an example that specifies Lisp mode and sets two variables with
;; -*-mode: Lisp; fill-column: 75; comment-column: 50; -*-
You can also specify the coding system for a file in this way: just
specify a value for the ``variable'' named
coding. The ``value''
must be a coding system name that Emacs recognizes. See Coding Systems.
A local variables list goes near the end of the file, in the
last page. (It is often best to put it on a page by itself.) The local
variables list starts with a line containing the string `
Local Variables:', and ends with a line containing the string `
between come the variable names and values, one set per line, as
variable: value'. The values are not
evaluated; they are used literally. If a file has both a local
variables list and a `
-*-' line, Emacs processes everything
in the `
-*-' line first, and everything in the local
variables list afterward.
Here is an example of a local variables list:
;;; Local Variables: *** ;;; mode:lisp *** ;;; comment-column:0 *** ;;; comment-start: ";;; " *** ;;; comment-end:"***" *** ;;; End: ***
As you see, each line starts with the prefix `
;;; ' and each line
ends with the suffix `
***'. Emacs recognizes these as the prefix
and suffix based on the first line of the list, by finding them
surrounding the magic string `
Local Variables:'; then it
automatically discards them from the other lines of the list.
The usual reason for using a prefix and/or suffix is to embed the
local variables list in a comment, so it won't confuse other programs
that the file is intended as input for. The example above is for a
language where comment lines start with `
;;; ' and end with
***'; the local values for
comment-end customize the rest of Emacs for this unusual syntax.
Don't use a prefix (or a suffix) if you don't need one.
Two ``variable names'' have special meanings in a local variables
list: a value for the variable
mode really sets the major mode,
and a value for the variable
eval is simply evaluated as an
expression and the value is ignored.
not real variables; setting variables named
in any other context has no special meaning. If
mode is used to
set a major mode, it should be the first ``variable'' in the list.
You can use the
mode ``variable'' to set minor modes as well as
major modes; in fact, you can use it more than once, first to set the
major mode and then to set minor modes which are specific to particular
buffers. But most minor modes should not be specified in the file in
any fashion, because they represent user preferences.
For example, you may be tempted to try to turn on Auto Fill mode with
a local variable list. That is a mistake. The choice of Auto Fill mode
or not is a matter of individual taste, not a matter of the contents of
particular files. If you want to use Auto Fill, set up major mode hooks
with your `
.emacs' file to turn it on (when appropriate) for you
alone (see Init File). Don't use a local variable list to impose
your taste on everyone.
The start of the local variables list must be no more than 3000
characters from the end of the file, and must be in the last page if the
file is divided into pages. Otherwise, Emacs will not notice it is
there. The purpose of this rule is so that a stray `
Local Variables:' not in the last page does not confuse Emacs, and so that
visiting a long file that is all one page and has no local variables
list need not take the time to search the whole file.
Use the command
normal-mode to reset the local variables and
major mode of a buffer according to the file name and contents,
including the local variables list if any. See Choosing Modes.
enable-local-variables controls whether to process
local variables in files, and thus gives you a chance to override them.
Its default value is
t, which means do process local variables in
files. If you set the value to
nil, Emacs simply ignores local
variables in files. Any other value says to query you about each file
that has local variables, showing you the local variable specifications
so you can judge.
eval ``variable,'' and certain actual variables, create a
special risk; when you visit someone else's file, local variable
specifications for these could affect your Emacs in arbitrary ways.
Therefore, the option
enable-local-eval controls whether Emacs
eval variables, as well variables with names that end
-function' or `
and certain other variables. The three possibilities for the option's
nil, and anything else, just as for
enable-local-variables. The default is
maybe, which is
nil, so normally Emacs does ask for
confirmation about file settings for these variables.