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.
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.el10. 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. This constant is also used to derive the name of a second dir-locals file .dir-locals-2.el. If this second dir-locals file is present, then that is loaded in addition to .dir-locals.el. This is useful when .dir-locals.el is under version control in a shared repository and cannot be used for personal customizations. The file specifies local variables as a specially formatted list; see Per-directory Local Variables in The GNU Emacs Manual, for more details.
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-directory-class, described below.
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
and its parent directories.
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 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
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.
This function assigns class to all the files in
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
Emacs uses this function internally when it loads directory variables
.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
This alist holds the class symbols and the associated variable
settings. It is updated by
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
updates this list.
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 (see File Local Variables).
The MS-DOS version of Emacs uses _dir-locals.el instead, due to limitations of the DOS filesystems.