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.el22 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
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
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
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
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
even if they use
c-mode because directory entries have priority
over mode entries.
You can specify the variables
unibyte in your .dir-locals.el, and they have the same
meanings as they would have in file local variables.
cannot be specified as a directory local variable. See File Variables.
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 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 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.