49.2.4 Local Variables in Files
A file can specify local variable values to use when editing the file with Emacs. Visiting the file or setting a major mode checks for local variable specifications; it automatically makes these variables local to the buffer, and sets them to the values specified in the file.
File local variables override directory local variables (see Directory Variables), if any are specified for a file’s directory.
| • Specifying File Variables |   | Specifying file local variables. |
| • Safe File Variables |   | Making sure file local variables are safe. |
49.2.4.1 Specifying File Variables​
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. The special variable/value pair mode: modename;, if present, specifies a major mode. The values are used literally, and not evaluated.
You can use M-x add-file-local-variable-prop-line instead of adding entries by hand. This command prompts for a variable and value, and adds them to the first line in the appropriate way. M-x delete-file-local-variable-prop-line prompts for a variable, and deletes its entry from the line. The command M-x copy-dir-locals-to-file-locals-prop-line copies the current directory-local variables to the first line (see Directory Variables).
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; -*-
Aside from mode, other keywords that have special meanings as file variables are coding, unibyte, and eval. 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).
Apart from 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. The exception to this is a major mode specification. Emacs applies this first, wherever it appears, since most major modes kill all local variables as part of their initialization.
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 comments start with ‘/*’ and end with ‘*/’.
If some unrelated text might look to Emacs as a local variables list, you can countermand that by inserting a form-feed character (a page delimiter, see Pages) after that text. Emacs only looks for file-local variables in the last page of a file, after the last page delimiter.
Instead of typing in the local variables list directly, you can use the command M-x add-file-local-variable. This prompts for a variable and value, and adds them to the list, adding the ‘Local Variables:’ string and start and end markers as necessary. The command M-x delete-file-local-variable deletes a variable from the list. M-x copy-dir-locals-to-file-locals copies directory-local variables to the list (see Directory Variables).
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 value 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 names have special meanings in a local variables list:
modeenables the specified major 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 load or compile a file of Emacs Lisp in unibyte mode, if the value ist. See Disabling Multibyte Characters in GNU Emacs Lisp Reference Manual.
These four keywords are not really variables; setting them in any other context has no special meaning.
Do not use the mode keyword for minor modes. To enable or disable a minor mode in a local variables list, use the eval keyword with a Lisp expression that runs the mode command (see Minor Modes). For example, the following local variables list enables ElDoc mode (see Lisp Doc) by calling eldoc-mode with no argument (calling it with an argument of 1 would do the same), and disables Font Lock mode (see Font Lock) by calling font-lock-mode with an argument of -1.
;; Local Variables:
;; eval: (eldoc-mode)
;; eval: (font-lock-mode -1)
;; End:
Note, however, that it is often a mistake to specify minor modes this way. Minor modes represent individual user preferences, and it may be inappropriate to impose your preferences on another user who might edit the file. If you wish to automatically enable or disable a minor mode in a situation-dependent way, it is often better to do it in a major mode hook (see Hooks).
Use the command M-x 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.
49.2.4.2 Safety of File Variables​
File-local variables can be dangerous; when you visit someone else’s file, there’s no telling what its local variables list could do to your Emacs. Improper values of the eval “variable", and other variables such as load-path, could execute Lisp code you didn’t intend to run.
Therefore, whenever Emacs encounters file local variable values that are not known to be safe, it displays the file’s entire local variables list, and asks you for confirmation before setting them. You can type y or SPC to put the local variables list into effect, or n to ignore it. When Emacs is run in batch mode (see Initial Options), it can’t really ask you, so it assumes the answer n.
Emacs normally recognizes certain variable/value pairs as safe. For instance, it is safe to give comment-column or fill-column any integer value. If a file specifies only known-safe variable/value pairs, Emacs does not ask for confirmation before setting them. Otherwise, you can tell Emacs to record all the variable/value pairs in this file as safe, by typing ! at the confirmation prompt. When Emacs encounters these variable/value pairs subsequently, in the same file or others, it will assume they are safe.
Some variables, such as load-path, are considered particularly risky: there is seldom any reason to specify them as local variables, and changing them can be dangerous. If a file contains only risky local variables, Emacs neither offers nor accepts ! as input at the confirmation prompt. If some of the local variables in a file are risky, and some are only potentially unsafe, you can enter ! at the prompt. It applies all the variables, but only marks the non-risky ones as safe for the future. If you really want to record safe values for risky variables, do it directly by customizing ‘safe-local-variable-values’ (see Easy Customization).
The variable enable-local-variables allows you to change the way Emacs processes local variables. Its default value is t, which specifies the behavior described above. If it is nil, Emacs simply ignores all file local variables. :safe means use only the safe values and ignore the rest. Any other value says to query you about each file that has local variables, without trying to determine whether the values are known to be safe.
The variable enable-local-eval controls whether Emacs processes eval variables. The three possibilities for the variable’s value are t, nil, and anything else, just as for enable-local-variables. The default is maybe, which is neither t nor nil, so normally Emacs does ask for confirmation about processing eval variables.
As an exception, Emacs never asks for confirmation to evaluate any eval form if that form occurs within the variable safe-local-eval-forms.