* doc/lispref/variables.texi (Directory Local Variables):

Document dir-locals wildcards

* lisp/files.el (dir-locals-file): Point to Info node.

* doc/emacs/custom.texi (Directory Variables):
Document dir-locals wildcards.

* etc/NEWS: Document new functionality.

2 files changed, 31 insertions, 14 deletions

diff --git a/doc/emacs/custom.texi b/doc/emacs/custom.texi
index 76c7261767a..8441c889bbf 100644
--- a/doc/emacs/custom.texi
+++ b/doc/emacs/custom.texi
@@ -1290,7 +1290,11 @@ accomplished with @dfn{directory-local variables}.
 named @file{.dir-locals.el}@footnote{ On MS-DOS, the name of this file
 should be @file{_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 @file{_dir-loc.el}.  } in a
+of the file will be truncated by the OS to @file{_dir-loc.el}.
+}@footnote{ You can also use files like @file{.dir-locals2.el}, which
+are loaded in addition.  This is useful when @file{.dir-locals.el} is
+under version control in a shared repository and can't be used for
+personal customizations.  } 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 @file{.dir-locals.el}, as though they had been defined as
diff --git a/doc/lispref/variables.texi b/doc/lispref/variables.texi
index 1d920942d10..f49d5062f20 100644
--- a/doc/lispref/variables.texi
+++ b/doc/lispref/variables.texi
@@ -1765,20 +1765,33 @@ variables: by putting them in a special file, or by defining a
 @dfn{project class} for that directory.
 
 @defvr Constant dir-locals-file
-This constant is the name of the file where Emacs expects to find the
-directory-local variables.  The name of the file is
-@file{.dir-locals.el}@footnote{
-The MS-DOS version of Emacs uses @file{_dir-locals.el} instead, due to
+This constant is a wildcard pattern matching the name of files where
+Emacs expects to find directory-local variables.  Its value is
+@file{.dir-locals*.el}@footnote{
+The MS-DOS version of Emacs uses @file{_dir-locals*.el} instead, due to
 limitations of the DOS filesystems.
-}.  A file by that name in a directory causes Emacs to apply its
-settings to any file in that directory or any of its subdirectories
-(optionally, you can exclude subdirectories; see below).
-If some of the subdirectories have their own @file{.dir-locals.el}
-files, Emacs uses the settings from the deepest file it finds starting
-from the file's directory and moving up the directory tree.  The file
-specifies local variables as a specially formatted list; see
-@ref{Directory Variables, , Per-directory Local Variables, emacs, The
-GNU Emacs Manual}, for more details.
+}, and the most common file name to use is @file{.dir-locals.el}.
+
+Any file matching this name pattern in a directory causes Emacs to
+apply its settings when visiting files in that directory or any of its
+subdirectories (optionally, you can exclude subdirectories; see
+below).
+If some of the subdirectories have their own file matching
+@file{.dir-locals*.el}, Emacs uses the settings from the deepest file
+it finds starting from the file's directory and moving up the
+directory tree.  The file specifies local variables as a specially
+formatted list; see @ref{Directory Variables, , Per-directory Local
+Variables, emacs, The GNU Emacs Manual}, for more details.
+
+If the same directory contains multiple such files (for instance,
+@file{.dir-locals.el} and @file{.dir-locals2.el}), then all of them
+are used in @code{string<} order.  This means that, if two files
+specify different values for the same variable, the file sorted after
+will override the value of the previous file (for instance, values in
+@file{.dir-locals2.el} override those in @file{.dir-locals.el}).  Note
+that, because of how lexicographic order works, values in
+@file{.dir-locals10.el} are overriden by values in @file{.dir-locals2.el}.
+This can be avoided by using @file{.dir-locals02.el} instead.
 @end defvr
 
 @defun hack-dir-local-variables