elisp: Directory Local Variables
11.12 Directory Local Variables
===============================
A directory can specify local variable values common to all files in
that directory; Emacs uses these to create buffer-local bindings for
those variables in buffers visiting any file in that directory. This is
useful when the files in the directory belong to some “project” and
therefore share the same local variables.
There are two different methods for specifying directory local
variables: by putting them in a special file, or by defining a “project
class” for that directory.
-- Constant: dir-locals-file
This constant is the name of the file where Emacs expects to find
the directory-local variables. The name of the file is
‘.dir-locals.el’(1). A file by that name in a directory causes
Emacs to apply its settings to any file in that directory or any of
its subdirectories (optionally, you can exclude subdirectories; see
below). If some of the subdirectories have their own
‘.dir-locals.el’ files, Emacs uses the settings from the deepest
file it finds starting from the file’s directory and moving up the
directory tree. The file specifies local variables as a specially
formatted list; see 
Per-directory Local Variables
(emacs)Directory Variables, for more details.
-- Function: hack-dir-local-variables
This function reads the ‘.dir-locals.el’ file and stores the
directory-local variables in ‘file-local-variables-alist’ that is
local to the buffer visiting any file in the directory, without
applying them. It also stores the directory-local settings in
‘dir-locals-class-alist’, where it defines a special class for the
directory in which ‘.dir-locals.el’ file was found. This function
works by calling ‘dir-locals-set-class-variables’ and
‘dir-locals-set-directory-class’, described below.
-- Function: hack-dir-local-variables-non-file-buffer
This function looks for directory-local variables, and immediately
applies them in the current buffer. It is intended to be called in
the mode commands for non-file buffers, such as Dired buffers, to
let them obey directory-local variable settings. For non-file
buffers, Emacs looks for directory-local variables in
‘default-directory’ and its parent directories.
-- Function: dir-locals-set-class-variables class variables
This function defines a set of variable settings for the named
CLASS, which is a symbol. You can later assign the class to one or
more directories, and Emacs will apply those variable settings to
all files in those directories. The list in VARIABLES can be of
one of the two forms: ‘(MAJOR-MODE . ALIST)’ or ‘(DIRECTORY .
LIST)’. With the first form, if the file’s buffer turns on a mode
that is derived from MAJOR-MODE, then the all the variables in the
associated ALIST are applied; ALIST should be of the form ‘(NAME .
VALUE)’. A special value ‘nil’ for MAJOR-MODE means the settings
are applicable to any mode. In ALIST, you can use a special NAME:
‘subdirs’. If the associated value is ‘nil’, the alist is only
applied to files in the relevant directory, not to those in any
subdirectories.
With the second form of VARIABLES, if DIRECTORY is the initial
substring of the file’s directory, then LIST is applied recursively
by following the above rules; LIST should be of one of the two
forms accepted by this function in VARIABLES.
-- Function: dir-locals-set-directory-class directory class &optional
mtime
This function assigns CLASS to all the files in ‘directory’ and its
subdirectories. Thereafter, all the variable settings specified
for CLASS will be applied to any visited file in DIRECTORY and its
children. CLASS must have been already defined by
‘dir-locals-set-class-variables’.
Emacs uses this function internally when it loads directory
variables from a ‘.dir-locals.el’ file. In that case, the optional
argument MTIME holds the file modification time (as returned by
‘file-attributes’). Emacs uses this time to check stored local
variables are still valid. If you are assigning a class directly,
not via a file, this argument should be ‘nil’.
-- Variable: dir-locals-class-alist
This alist holds the class symbols and the associated variable
settings. It is updated by ‘dir-locals-set-class-variables’.
-- Variable: dir-locals-directory-cache
This alist holds directory names, their assigned class names, and
modification times of the associated directory local variables file
(if there is one). The function ‘dir-locals-set-directory-class’
updates this list.
-- Variable: enable-dir-local-variables
If ‘nil’, directory-local variables are ignored. This variable may
be useful for modes that want to ignore directory-locals while
still respecting file-local variables (File Local
Variables).
---------- Footnotes ----------
(1) The MS-DOS version of Emacs uses ‘_dir-locals.el’ instead, due to
limitations of the DOS filesystems.
Info Catalog
elisp: File Local Variables
elisp: Variables
elisp: Variable Aliases