(X)Emacs allows per-file customization of various editing options. A file can specify various parameters appropriate for editing it. This is done by setting local variables to appropriate values when the file is opened.

You can specify a local variables list either in multiple lines at the end of a file, or in the first line of the file.

  • To specify at the end of the file, you must place the lines either on the last page of the file (if divided into pages, i.e. if it contains form feed characters) or within the last 3000 characters of the file. In practice, just put them at the end of the file, and all will be well.

Put a line containing "Local Variables" to start the section. The portion of the line before the string is the prefix, and the portion after the string the suffix. Every line specifies one local variable, and must use the same prefix and suffix. The format of the variable specifier is "VARIABLE: VALUE", where VALUE is some (constant) Emacs Lisp value.

Two special specifiers are defined. If you (attempt to) assign a value to the special variable mode, that major mode will be applied to the file. And if you (attempt to) assign a value to the special variable eval, the Emacs Lisp code "assigned" will be evaluated (see more about this below).

End the section with a specifier "End:".

For example, .h files are usually C header files. But in some project, I might want to keep my C++ headers in them instead. Additionally, suppose my collaborators on this project wish to use 4-space tabs. I can accommodate these changes, on a per-file basis, by appending these lines to my .h files:

// Local Variables:
// mode:c++
// tab-width:4
// End:

  • To put local variable specifiers in the first line of the file, place them between "-*-", separated by semicolons. The example above might become

    // myfile.h    For (X)Emacs: -*- mode:c++; tab-width:4 -*-
    

    A special abbreviation is allowed: "-*- MODE -*-" specifies just the file's major mode. To start an outline-mode file, it's easiest just to have the first line contain "-*- outline -*-".

  • You can, of course, mix the two forms in one file. Note that you cannot customise the parameters for finding and processing the local variables. This wouldn't make any sense: if you could customise the parameters for finding customization, you would be unable to find it when editing others' files!

    Security

    Setting variables automatically is a bad idea. Executing arbitrary code automatically is even worse -- see all the problems with VBA's macro viruses, which arise from the decisions at Microsoft to make automated code execution practically mandatory for many types of templating tasks.

    (X)Emacs has 2 variables to protect you:

    • enable-local-eval is consulted before evaluating any "eval" code or setting hooks and other variables whose value is executable code. If t, evaluation will be performed; if nil, blocked; otherwise (a good value is "'maybe" or "'ask"), the code will be displayed, and you will be asked whether to allow it or not. This variable should probably never be set to t. Users of Outlook and Outlook Express can probably ignore this advice, given their email client's penchant for executing any code it can find...
    • enable-local-variables is consulted before setting any other variables. It takes the same values, but you can probably allow yourself more latitude here.

    My advice: Set both to nil if really paranoid. NEVER set enable-local-eval to t; if you have to, set it to 'ask. Set enable-local-variables to 'ask too -- unless you're sure that Emacs has no local variables which can harm you (I'm not).

    When set to 'ask, NEVER approve anything you don't understand. In particular, if you don't understand what the Emacs Lisp code displayed is trying to do, or if it isn't commented to your liking, or if the comments don't match the code, DO NOT approve an eval.

    Usage

    This feature should be used to set up variables pertaining to universal properties of the file, not to your own preferences. Setting major modes, tab widths, and the like is good use of the feature: everyone should view and edit the file correctly. Setting most minor modes (auto-fill-mode and font-lock-mode seem to be the most common misuses here) and personal options (such as c-hungy-delete-key) is flat-out wrong: others might not wish to view the file with these "enhancements". Minor modes such as outline-minor-mode, however, belong of course to the first category, and can be set if appropriate.

    Log in or registerto write something here or to contact authors.