(emacs.info) File Variables

Info Catalog

(emacs.info) Locals

(emacs.info) Variables

 
 Local Variables in Files
 ------------------------
 
    A file can specify local variable values for use when you edit the
 file with Emacs.  Visiting the file 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 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 variables/value pairs in this way, each
 pair with a colon and semicolon as shown above.  `mode: MODENAME;'
 specifies the major mode; this should come first in the line.  The
 VALUEs are not evaluated; they are used literally.  Here is an example
 that specifies Lisp mode and sets two variables with numeric values:
 
      ;; -*-mode: Lisp; fill-column: 75; comment-column: 50; -*-
 
    You can also specify the coding system for a file in this way: just
 specify a value for the "variable" named `coding'.  The "value" must be
 a coding system name that Emacs recognizes.   Coding Systems.
 
    A "local variables list" goes near the end of the file, in the last
 page.  (It is often best to put it on a page by itself.)  The 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, as
 `VARIABLE: VALUE'.  The VALUEs are not evaluated; they are used
 literally.  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.
 
    Here is an example of a local variables list:
 
      ;;; Local Variables: ***
      ;;; mode:lisp ***
      ;;; comment-column:0 ***
      ;;; comment-start: ";;; "  ***
      ;;; comment-end:"***" ***
      ;;; End: ***
 
    As you see, each line starts with the prefix `;;; ' and each line
 ends with the suffix ` ***'.  Emacs recognizes these as the prefix and
 suffix based on the first line of the list, by finding them surrounding
 the magic string `Local Variables:'; then it 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 as input for.  The example above is for a
 language where comment lines start with `;;; ' and end with `***'; the
 local values for `comment-start' and `comment-end' customize the rest
 of Emacs for this unusual syntax.  Don't use a prefix (or a suffix) if
 you don't need one.
 
    Two "variable names" have special meanings in a local variables
 list: a value for the variable `mode' really sets the major mode, and a
 value for the variable `eval' is simply evaluated as an expression and
 the value is ignored.  `mode' and `eval' are not real variables;
 setting variables named `mode' and `eval' in any other context has no
 special meaning.  If `mode' is used to set a major mode, it should be
 the first "variable" in the list.
 
    You can use the `mode' "variable" to set minor modes as well as
 major modes; in fact, you can use it more than once, first to set the
 major mode and then to set minor modes which are specific to particular
 buffers.  But most minor modes should not be specified in the file in
 any fashion, because they represent user preferences.
 
    For example, you may be tempted to try to turn on Auto Fill mode with
 a local variable list.  That is a mistake.  The choice of Auto Fill mode
 or not is a matter of individual taste, not a matter of the contents of
 particular files.  If you want to use Auto Fill, set up major mode hooks
 with your `.emacs' file to turn it on (when appropriate) for you alone
 ( Init File).  Don't use a local variable list to impose your
 taste on everyone.
 
    The start of the local variables list must be no more than 3000
 characters from the end of the file, and must be in the last page if the
 file is divided into pages.  Otherwise, Emacs will not notice it is
 there.  The purpose of this rule is so that a stray `Local Variables:'
 not in the last page does not confuse Emacs, and so that visiting a
 long file that is all one page and has no local variables list need not
 take the time to search the whole file.
 
    Use the command `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.
 
    The variable `enable-local-variables' controls whether to process
 local variables in files, and thus gives you a chance to override them.
 Its default value is `t', which means do process local variables in
 files.  If you set the value to `nil', Emacs simply ignores local
 variables in files.  Any other value says to query you about each file
 that has local variables, showing you the local variable specifications
 so you can judge.
 
    The `eval' "variable," and certain actual variables, create a
 special risk; when you visit someone else's file, local variable
 specifications for these could affect your Emacs in arbitrary ways.
 Therefore, the option `enable-local-eval' controls whether Emacs
 processes `eval' variables, as well variables with names that end in
 `-hook', `-hooks', `-function' or `-functions', and certain other
 variables.  The three possibilities for the option'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 file settings for these variables.
 

Info Catalog

(emacs.info) Locals

(emacs.info) Variables