Info Catalog emacs: File Variables emacs: Variables

emacs: Directory Variables

 
 51.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”.
 
    The usual way to define directory-local variables is to put a file
 named ‘.dir-locals.el’(1) 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 (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’.
 
    The ‘.dir-locals.el’ file should hold a specially-constructed list,
 which maps major mode names (symbols) to alists (
 (elisp)Association Lists).  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 (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
 (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 (Dired).
 
    ---------- Footnotes ----------
 
    (1) 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’.
 

Info Catalog emacs: File Variables emacs: Variables