Next: , Up: Local Variables in Files   [Contents][Index]

51.2.4.1 Specifying File Variables

Here is one way to specify local variables, 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.

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; -*-

After any change to the ‘-*-’ line, type M-x normal-mode to re-interpret it. See Choosing File Modes.

Aside from mode, other keywords that have special meanings as file variables are coding, unibyte, and eval. These keywords are described later.

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 variables in the second line if the first line specifies an interpreter. The same is true for man pages that start with the magic string ‘'\"’ to specify a list of troff preprocessors (not all do, however).

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. The command M-x delete-file-local-variable-prop-line prompts for a variable, and deletes its entry from the line. If there are any directory-local variables (see Per-Directory Local Variables), the command M-x copy-dir-locals-to-file-locals-prop-line will copy them to the first line.

You also can define file local variables using a local variables list near the end of the file.

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 ‘*/’.

The start of the local variables list must be no more than 3000 characters from the end of the file, and it must be on the last page if the file is divided into pages. If some unrelated text might look to Emacs like a local variables list, you can countermand that by inserting a form-feed character (a page delimiter, see Pages) after that text.

After any change to the local variables, type M-x normal-mode to re-read them. See Choosing File Modes.

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:

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).

Some names have special meanings in a local variables list:

These four keywords are not really variables; setting them in any other context has no special meaning.

If you’re editing a file across Emacs versions, and a new mode has been introduced to handle a file in a newer Emacs version, you can use several mode entries to use the new mode (called my-new-mode) in the new Emacs, and fall back to the old mode (called my-old-mode) in older Emacs versions. If you’re enabling the modes in the first line of the file, can say: 

-*- mode: my-old; mode: my-new -*-

Emacs will use the final defined mode it finds, so in older Emacs versions it will ignore my-new-mode, while in Emacs versions where my-new-mode is defined, it’ll ignore my-old-mode. Similarly, in a local variables block at the end of the file: 

Local variables:
mode: my-old
mode: my-new

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 Programming Language 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).

Next: Safety of File Variables, Up: Local Variables in Files   [Contents][Index]