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 (without the “-mode” suffix). 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 Per-Directory Local 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 Per-Directory Local 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:

• mode enables the specified major mode.

• eval evaluates the specified Lisp expression (the value returned by that expression is ignored).

• coding specifies the coding system for character code conversion of this file. See Coding Systems.

• unibyte says to load or compile a file of Emacs Lisp in unibyte mode, if the value is t. 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 Emacs Lisp Documentation Lookup) 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 mode) 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 File Modes.