There are two ways to specify file 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 variable/value pairs in this way, each
pair with a colon and semicolon as shown above. The special
;, if present,
specifies a major or minor mode; if you use this to specify a major
mode, it should come first in the line. The values are used
literally, and not evaluated.
You can use the command
instead of adding entries by hand. It prompts for a variable
and value, and adds them to the first line in the appropriate way.
delete-file-local-variable-prop-line deletes a
variable from the line. The command
copy-dir-locals-to-file-locals-prop-line copies directory-local
variables (see Directory Variables) to the first line.
Here is an example first line that specifies Lisp mode and sets two variables with numeric values:
;; -*- mode: Lisp; fill-column: 75; comment-column: 50; -*-
mode, other keywords that have special meanings as
file variables are
These are described below.
In shell scripts, the first line is used to identify the script interpreter, so you cannot put any local variables there. To accommodate this, Emacs looks for local variable specifications in the second line if the first line specifies an interpreter. The same is true for man pages which start with the magic string ‘'\"’ to specify a list of troff preprocessors (not all do, however).
Instead of using a ‘-*-’ line, you can define file local variables using a local variables list near the end of the file. The start of the local variables list should be no more than 3000 characters from the end of the file, and must be on the last page if the file is divided into pages.
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.
A local variables list starts with a line containing the string ‘Local Variables:’, and ends with a line containing the string ‘End:’. In between come the variable names and values, one set per line, like this:
/* Local Variables: */ /* mode:c */ /* comment-column:0 */ /* End: */
In this example, each line starts with the prefix ‘/*’ and ends with the suffix ‘*/’. Emacs recognizes the prefix and suffix by finding them surrounding the magic string ‘Local Variables:’, on the first line of the list; it then 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 for. The example above is for the C programming language, where comment lines start with ‘/*’ and end with ‘*/’.
You can construct the local variables list yourself, or use the
add-file-local-variable. This prompts for a variable
and value, and adds them to the list. If necessary, it also adds the
start and end markers. The command
deletes a variable from the list. The command
copy-dir-locals-to-file-locals copies directory-local variables
(see Directory Variables) to the list.
As with the ‘-*-’ line, the variables in a local variables list are used literally, and are not evaluated first. If you want to split a long string across multiple lines of the file, you can use backslash-newline, which is ignored in Lisp string constants; you should put the prefix and suffix on each line, even lines that start or end within the string, as they will be stripped off when processing the list. Here is an example:
# Local Variables: # compile-command: "cc foo.c -Dfoo=bar -Dhack=whatever \ # -Dmumble=blaah" # End:
Some “variable names” have special meanings in a local variables list:
modeenables the specified major or minor mode.
evalevaluates the specified Lisp expression (the value returned by that expression is ignored).
codingspecifies the coding system for character code conversion of this file. See Coding Systems.
unibytesays to visit the file in a unibyte buffer, if the value is
t. See Enabling Multibyte.
These four “variables” are not really variables; setting them in any other context has no special meaning.
mode is used to set a major mode, it should be the
first “variable” in the list. Otherwise, the entries that precede
it will usually have no effect, since most major modes kill all local
variables as part of their initialization.
You can use the
mode “variable” to enable minor modes as
well as the major modes; in fact, you can use it more than once, first
to set the major mode and then to enable minor modes which are
specific to particular buffers.
Often, however, it is a mistake to enable minor modes this way. Most minor modes, like Auto Fill mode, represent individual user preferences. If you want to use a minor mode, it is better to set up major mode hooks with your init file to turn that minor mode on for yourself alone (see Init File), instead of using a local variable list to impose your taste on everyone.
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.