57.3.5 Per-Directory Local Variables

A project is a collection of files on which you work together. Usually, the project's files are kept in one or more directories. Occasionally, you may wish to define Emacs settings that are common to all the files that belong to the project.

Emacs provides two ways to specify settings that are applicable to files in a specific directory: you can put a special file in that directory, or you can define a project class for that directory.

If you put a file with a special name .dir-locals.el¹ in a directory, Emacs will read it when it visits any file in that directory or any of its subdirectories, and apply the settings it specifies to the file's buffer. 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.)

The .dir-locals.el file should hold a specially-constructed list. This list maps Emacs mode names (symbols) to alists; each alist specifies values for variables to use when the respective mode is turned on. The special mode name ‘nil’ means that its alist applies to any mode. Instead of a mode name, you can specify a string that is a name of a subdirectory of the project's directory; then the corresponding alist applies to all the files in that subdirectory.

Here's an example of a .dir-locals.el file:

     ((nil . ((indent-tabs-mode . t)
              (tab-width . 4)
              (fill-column . 80)))
      (c-mode . ((c-file-style . "BSD")))
      (java-mode . ((c-file-style . "BSD")))
      ("src/imported"
       . ((nil . ((change-log-default-name . "ChangeLog.local"))))))

This example shows some settings for a hypothetical project. It sets ‘indent-tabs-mode’, tab-width, and fill-column for any file in the project's directory tree, and it sets the indentation style for any C or Java source file. Finally, it specifies a different ChangeLog file name for any file in the src/imported subdirectory of the directory where you put the .dir-locals.el file.

You can edit the .dir-locals.el file by hand, or use the command add-dir-local-variable. This prompts for a mode (or subdirectory), variable and value, and adds an entry to the file. The command delete-dir-local-variable deletes an entry. The command copy-file-locals-to-dir-locals copies file local variables (see File Variables) to the .dir-locals.el file.

Another method of specifying directory-local variables is to explicitly define a project class using dir-locals-set-class-variables, and then tell Emacs which directories correspond to that class, using dir-locals-set-directory-class. You can put calls to these functions in your ~/.emacs init file; this can be useful when you can't put .dir-locals.el in the directory for some reason, or if you want to keep in a single place settings for several directories that don't have a common parent. 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)

Unsafe directory-local variables are handled in the same way as unsafe file-local variables (see Safe File Variables).