diff options
Diffstat (limited to 'devdocs/elisp/directory-local-variables.html')
| -rw-r--r-- | devdocs/elisp/directory-local-variables.html | 26 |
1 files changed, 26 insertions, 0 deletions
diff --git a/devdocs/elisp/directory-local-variables.html b/devdocs/elisp/directory-local-variables.html new file mode 100644 index 00000000..2c337dfa --- /dev/null +++ b/devdocs/elisp/directory-local-variables.html @@ -0,0 +1,26 @@ + <h3 class="section">Directory Local Variables</h3> <p>A directory can specify local variable values common to all files in that directory; Emacs uses these to create buffer-local bindings for those variables in buffers visiting any file in that directory. This is useful when the files in the directory belong to some <em>project</em> and therefore share the same local variables. </p> <p>There are two different methods for specifying directory local variables: by putting them in a special file, or by defining a <em>project class</em> for that directory. </p> <dl> <dt id="dir-locals-file">Constant: <strong>dir-locals-file</strong> +</dt> <dd><p>This constant is the name of the file where Emacs expects to find the directory-local variables. The name of the file is <samp>.dir-locals.el</samp><a id="DOCF11" href="#FOOT11"><sup>11</sup></a>. 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 <samp>.dir-locals.el</samp> files, Emacs uses the settings from the deepest file it finds starting from the file’s directory and moving up the directory tree. This constant is also used to derive the name of a second dir-locals file <samp>.dir-locals-2.el</samp>. If this second dir-locals file is present, then that is loaded in addition to <samp>.dir-locals.el</samp>. This is useful when <samp>.dir-locals.el</samp> is under version control in a shared repository and cannot be used for personal customizations. The file specifies local variables as a specially formatted list; see <a href="https://www.gnu.org/software/emacs/manual/html_node/emacs/Directory-Variables.html#Directory-Variables">Per-directory Local Variables</a> in <cite>The GNU Emacs Manual</cite>, for more details. </p></dd> +</dl> <dl> <dt id="hack-dir-local-variables">Function: <strong>hack-dir-local-variables</strong> +</dt> <dd><p>This function reads the <code>.dir-locals.el</code> file and stores the directory-local variables in <code>file-local-variables-alist</code> that is local to the buffer visiting any file in the directory, without applying them. It also stores the directory-local settings in <code>dir-locals-class-alist</code>, where it defines a special class for the directory in which <samp>.dir-locals.el</samp> file was found. This function works by calling <code>dir-locals-set-class-variables</code> and <code>dir-locals-set-directory-class</code>, described below. </p></dd> +</dl> <dl> <dt id="hack-dir-local-variables-non-file-buffer">Function: <strong>hack-dir-local-variables-non-file-buffer</strong> +</dt> <dd><p>This function looks for directory-local variables, and immediately applies them in the current buffer. It is intended to be called in the mode commands for non-file buffers, such as Dired buffers, to let them obey directory-local variable settings. For non-file buffers, Emacs looks for directory-local variables in <code>default-directory</code> and its parent directories. </p></dd> +</dl> <dl> <dt id="dir-locals-set-class-variables">Function: <strong>dir-locals-set-class-variables</strong> <em>class variables</em> +</dt> <dd> +<p>This function defines a set of variable settings for the named <var>class</var>, which is a symbol. You can later assign the class to one or more directories, and Emacs will apply those variable settings to all files in those directories. The list in <var>variables</var> can be of one of the two forms: <code>(<var>major-mode</var> . <var>alist</var>)</code> or <code>(<var>directory</var> . <var>list</var>)</code>. With the first form, if the file’s buffer turns on a mode that is derived from <var>major-mode</var>, then all the variables in the associated <var>alist</var> are applied; <var>alist</var> should be of the form <code>(<var>name</var> . <var>value</var>)</code>. A special value <code>nil</code> for <var>major-mode</var> means the settings are applicable to any mode. In <var>alist</var>, you can use a special <var>name</var>: <code>subdirs</code>. If the associated value is <code>nil</code>, the alist is only applied to files in the relevant directory, not to those in any subdirectories. </p> <p>With the second form of <var>variables</var>, if <var>directory</var> is the initial substring of the file’s directory, then <var>list</var> is applied recursively by following the above rules; <var>list</var> should be of one of the two forms accepted by this function in <var>variables</var>. </p> +</dd> +</dl> <dl> <dt id="dir-locals-set-directory-class">Function: <strong>dir-locals-set-directory-class</strong> <em>directory class &optional mtime</em> +</dt> <dd> +<p>This function assigns <var>class</var> to all the files in <code>directory</code> and its subdirectories. Thereafter, all the variable settings specified for <var>class</var> will be applied to any visited file in <var>directory</var> and its children. <var>class</var> must have been already defined by <code>dir-locals-set-class-variables</code>. </p> <p>Emacs uses this function internally when it loads directory variables from a <code>.dir-locals.el</code> file. In that case, the optional argument <var>mtime</var> holds the file modification time (as returned by <code>file-attributes</code>). Emacs uses this time to check stored local variables are still valid. If you are assigning a class directly, not via a file, this argument should be <code>nil</code>. </p> +</dd> +</dl> <dl> <dt id="dir-locals-class-alist">Variable: <strong>dir-locals-class-alist</strong> +</dt> <dd><p>This alist holds the class symbols and the associated variable settings. It is updated by <code>dir-locals-set-class-variables</code>. </p></dd> +</dl> <dl> <dt id="dir-locals-directory-cache">Variable: <strong>dir-locals-directory-cache</strong> +</dt> <dd><p>This alist holds directory names, their assigned class names, and modification times of the associated directory local variables file (if there is one). The function <code>dir-locals-set-directory-class</code> updates this list. </p></dd> +</dl> <dl> <dt id="enable-dir-local-variables">Variable: <strong>enable-dir-local-variables</strong> +</dt> <dd><p>If <code>nil</code>, directory-local variables are ignored. This variable may be useful for modes that want to ignore directory-locals while still respecting file-local variables (see <a href="file-local-variables">File Local Variables</a>). </p></dd> +</dl><div class="_attribution"> + <p class="_attribution-p"> + Copyright © 1990-1996, 1998-2022 Free Software Foundation, Inc. <br>Licensed under the GNU GPL license.<br> + <a href="https://www.gnu.org/software/emacs/manual/html_node/elisp/Directory-Local-Variables.html" class="_attribution-link">https://www.gnu.org/software/emacs/manual/html_node/elisp/Directory-Local-Variables.html</a> + </p> +</div> |