From 8b8a4c0aeb21692970fe919e96ad4b832fe1078b Mon Sep 17 00:00:00 2001 From: Eli Zaretskii Date: Sat, 22 Sep 2018 12:06:51 +0300 Subject: [PATCH] Improve documentation of directory-local variables * lisp/files.el (hack-local-variables, normal-mode) (after-find-file, find-file-hook): Mention directory-local variables in the doc strings. Suggested by Marcin Borkowski . * doc/emacs/custom.texi (File Variables, Directory Variables): Clarify that directory-local variables are overridden by file-local ones. --- doc/emacs/custom.texi | 11 ++++++++++- lisp/files.el | 9 ++++++--- 2 files changed, 16 insertions(+), 4 deletions(-) diff --git a/doc/emacs/custom.texi b/doc/emacs/custom.texi index 141fa045b63..b93009ad216 100644 --- a/doc/emacs/custom.texi +++ b/doc/emacs/custom.texi @@ -1059,6 +1059,10 @@ local variable specifications; it automatically makes these variables local to the buffer, and sets them to the values specified in the file. + File local variables override directory local variables +(@pxref{Directory Variables}), if any are specified for a file's +directory. + @menu * Specifying File Variables:: Specifying file local variables. * Safe File Variables:: Making sure file local variables are safe. @@ -1309,7 +1313,12 @@ confirmation about processing @code{eval} 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 @dfn{directory-local variables}. +accomplished with @dfn{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. @cindex @file{.dir-locals.el} file The usual way to define directory-local variables is to put a file diff --git a/lisp/files.el b/lisp/files.el index 4eb1560a20d..a3e72e2ce9c 100644 --- a/lisp/files.el +++ b/lisp/files.el @@ -493,7 +493,8 @@ The functions are called in the order given until one of them returns non-nil.") (defcustom find-file-hook nil "List of functions to be called after a buffer is loaded from a file. The buffer's local variables (if any) will have been processed before the -functions are called." +functions are called. This includes directory-local variables, if any, +for the file's directory." :group 'find-file :type 'hook :options '(auto-insert) @@ -2369,7 +2370,7 @@ the file contents into it using `insert-file-contents-literally'." _after-find-file-from-revert-buffer nomodes) "Called after finding a file and by the default revert function. -Sets buffer mode, parses local variables. +Sets buffer mode, parses file-local and directory-local variables. Optional args ERROR, WARN, and NOAUTO: ERROR non-nil means there was an error in reading the file. WARN non-nil means warn if there exists an auto-save file more recent than the visited file. @@ -2454,7 +2455,7 @@ unless NOMODES is non-nil." (defun normal-mode (&optional find-file) "Choose the major mode for this buffer automatically. -Also sets up any specified local variables of the file. +Also sets up any specified local variables of the file or its directory. Uses the visited file name, the -*- line, and the local variables spec. This function is called automatically from `find-file'. In that case, @@ -3485,6 +3486,8 @@ DIR-NAME is the name of the associated directory. Otherwise it is nil." (defun hack-local-variables (&optional handle-mode) "Parse and put into effect this buffer's local variables spec. +For buffers visitying files, also puts into effect directory-local +variables. Uses `hack-local-variables-apply' to apply the variables. If HANDLE-MODE is nil, we apply all the specified local -- 2.39.2