49.2.5 Per-Directory Local Variables
Sometimes, you may wish to define the same set of local variables to all the files in a certain directory and its subdirectories, such as the directory tree of a large software project. This can be accomplished with directory-local variables. File local variables override directory local variables, so if some of the files in a directory need specialized settings, you can specify the settings for the majority of the directory’s files in directory variables, and then define file local variables in a few files which need the general settings overridden.
The usual way to define directory-local variables is to put a file
named .dir-locals.el 22 in a directory. Whenever Emacs visits any file in that directory or
any of its subdirectories, it will apply the directory-local variables
specified in .dir-locals.el, as though they had been defined as
file-local variables for that file (see Local Variables in Files). Emacs
searches for .dir-locals.el starting in the directory of the
visited file, and moving up the directory tree. To avoid slowdown,
this search is skipped for remote files. If needed, the search can be
extended for remote files by setting the variable
enable-remote-dir-locals to t.
You can also use .dir-locals-2.el; if found, Emacs loads it
in addition to .dir-locals.el. This is useful when
.dir-locals.el is under version control in a shared repository
and can’t be used for personal customizations.
The .dir-locals.el file should hold a specially-constructed
list, which maps major mode names (symbols) to alists
(see Association Lists in The Emacs Lisp Reference Manual).
Each alist entry consists of a variable name and the directory-local
value to assign to that variable, when the specified major mode is
enabled. Instead of a mode name, you can specify ‘ nil’, which
means that the alist applies to any mode; or you can specify a
subdirectory (a string), in which case the alist applies to all
files in that subdirectory.
Here’s an example of a .dir-locals.el file:
((nil . ((indent-tabs-mode . t)
(fill-column . 80)
(mode . auto-fill)))
(c-mode . ((c-file-style . "BSD")
(subdirs . nil)))
("src/imported"
. ((nil . ((change-log-default-name
. "ChangeLog.local"))))))
This sets the variables ‘ indent-tabs-mode’ and fill-column
for any file in the directory tree, and the indentation style for any
C source file. The special mode element specifies the minor
mode to be enabled. So (mode . auto-fill) specifies that the
minor mode auto-fill-mode needs to be enabled. The special
subdirs element is not a variable, but a special keyword which
indicates that the C mode settings are only to be applied in the
current directory, not in any subdirectories. Finally, it specifies a
different ChangeLog file name for any file in the
src/imported subdirectory.
If the .dir-locals.el file contains multiple different values
for a variable using different mode names or directories, the values
will be applied in an order such that the values for more specific
modes take priority over more generic modes. Values specified under a
directory have even more priority. For example:
((nil . ((fill-column . 40)))
(c-mode . ((fill-column . 50)))
(prog-mode . ((fill-column . 60)))
("narrow-files" . ((nil . ((fill-column . 20))))))
Files that use c-mode also match prog-mode because the
former inherits from the latter. The value used for
fill-column in C files will however be 50 because the
mode name is more specific than prog-mode. Files using other
modes inheriting from prog-mode will use 60. Any file
under the directory narrow-files will use the value 20
even if they use c-mode because directory entries have priority
over mode entries.
You can specify the variables mode, eval, and
unibyte in your .dir-locals.el, and they have the same
meanings as they would have in file local variables. coding
cannot be specified as a directory local variable. See Local Variables in Files.
The special key auto-mode-alist in a .dir-locals.el lets
you set a file’s major mode. It works much like the variable
auto-mode-alist (see Choosing File Modes). For example, here is
how you can tell Emacs that .def source files in this directory
should be in C mode:
((auto-mode-alist . (("\\.def\\'" . c-mode))))
Instead of editing the .dir-locals.el file by hand, you can
use the command M-x add-dir-local-variable. This prompts for a
mode or subdirectory, and for variable and value, and adds the
entry defining the directory-local variable. M-x delete-dir-local-variable deletes an entry. M-x copy-file-locals-to-dir-locals copies the file-local variables in the
current file into .dir-locals.el.
Another method of specifying directory-local variables is to define
a group of variables/value pairs in a directory class, using the
dir-locals-set-class-variables function; then, tell Emacs which
directories correspond to the class by using the
dir-locals-set-directory-class function. These function calls
normally go in your initialization file (see The Emacs Initialization File). This
method is useful when you can’t put .dir-locals.el in a
directory for some reason. For example, you could apply settings to
an unwritable directory this way:
(dir-locals-set-class-variables 'unwritable-directory
'((nil . ((some-useful-setting . value)))))
(dir-locals-set-directory-class
"/usr/include/" 'unwritable-directory)
If a variable has both a directory-local and file-local value specified, the file-local value takes effect. Unsafe directory-local variables are handled in the same way as unsafe file-local variables (see Safety of File Variables).
Directory-local variables also take effect in certain buffers that do not visit a file directly but perform work within a directory, such as Dired buffers (see Dired, the Directory Editor).
Footnotes
(22)
On MS-DOS, the name of this file should be _dir-locals.el, due
to limitations of the DOS filesystems. If the filesystem is limited
to 8+3 file names, the name of the file will be truncated by the OS to
_dir-loc.el.