emacs: Specifying File Variables
51.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 (
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, 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 (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:
• ‘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. Coding Systems.
• ‘unibyte’ says to load or compile a file of Emacs Lisp in unibyte
mode, if the value is ‘t’. Disabling Multibyte Characters
(elisp)Disabling Multibyte.
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 (Minor Modes). For
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 (
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 (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. Choosing Modes.
Info Catalog
emacs: File Variables
emacs: Safe File Variables