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.
The usual way to define directory-local variables is to put a file
named .dir-locals.el18 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 File Variables). 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
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 name (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))) (c-mode . ((c-file-style . "BSD") (subdirs . nil))) ("src/imported" . ((nil . ((change-log-default-name . "ChangeLog.local"))))))
This sets ‘indent-tabs-mode’ and
fill-column for any file
in the directory tree, and the indentation style for any C source
file. 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.
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 name, 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 Init 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 Safe 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).
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.