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²² 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 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 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).