Up: Local Variables   [Index]

C.3.1 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.

There are two ways to specify file local variable values:

  1. in the first or second 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 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.

    Keywords that have special meanings as file variables (including the local variables list) are:

    mode

    enables the specified major mode

    coding

    specifies the coding system for character code conversion

    unibyte

    load or compile a file of Emacs Lisp in unibyte mode if value is t

    eval

    evaluate the specified Lisp expression (the value returned is ignored)

  2. with a local variables list. 
    Local Variables:
<variable>: <value>
End:

    Instead of typing in the local variables list directly, you can use the command ‘M-x add-file-local-variable’. 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.

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

Processing Local Variables

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

Up: Local Variables   [Index]