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.el1 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
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
You can edit the .dir-locals.el file by hand, or use the
add-dir-local-variable. This prompts for a mode (or
subdirectory), variable and value, and adds an entry to the file.
delete-dir-local-variable deletes an entry. The
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
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).
 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.