ディレクトリでは、そのディレクトリ内のすべてのファイルに共通するローカル変数の値を指定できます。Emacsはこれを利用して、そのディレクトリ内の任意のファイルを参照しているバッファにおいて、それらの変数に対するバッファローカルなバインディングを作成します。これは、ディレクトリ内のファイルが何らかのプロジェクトに属しており、したがって同じローカル変数を共有している場合に有用です。
ディレクトリローカル変数を指定する方法には、専用のファイルに記述する方法と、そのディレクトリ用のプロジェクトクラスを定義する方法の2通りがあります。
この定数は、Emacsがディレクトリローカル変数の所在として想定するファイル名です。ファイル名は .dir-locals.el14 です。あるディレクトリにこの名前のファイルが存在すると、Emacsはそのディレクトリ内またはそのサブディレクトリ内のあらゆるファイルに設定を適用します（オプションでサブディレクトリを除外することも可能です。詳細は後述します）。サブディレクトリの一部に独自の .dir-locals.el ファイルがある場合、Emacsはファイルのディレクトリからディレクトリツリーを遡って見つかった最も深いファイルの設定を使用します。この定数は、2つ目の dir-locals ファイル .dir-locals-2.el の名前を導出するためにも使用されます。この2つ目の dir-locals ファイルが .dir-locals.el と同じディレクトリに存在する場合、.dir-locals.el に加えて読み込まれます。これは、.dir-locals.el が共有リポジトリでバージョン管理されており、個人のカスタマイズに使用できない場合に有用です。このファイルでは、ローカル変数が特殊な形式のリストとして指定されています。詳細については、The GNU Emacs Manual の Per-directory Local Variables を参照してください。
この関数は .dir-locals.el
ファイルを読み込み、ディレクトリローカル変数を、ディレクトリ内の任意のファイルを参照しているバッファにローカルな file-local-variables-alist に、適用せずに格納します。また、ディレクトリローカル設定を
dir-locals-class-alist に格納し、そこで .dir-locals.el ファイルが見つかったディレクトリ用の特別なクラスを定義します。この関数は、後述する
dir-locals-set-class-variables および dir-locals-set-directory-class を呼び出すことで動作します。
この関数はディレクトリローカル変数を検索し、現在のバッファに即座に適用します。Diredバッファなどのファイル以外のバッファにおいて、ディレクトリローカル変数の設定を反映させるために、モードコマンド内で呼び出すことを想定しています。ファイル以外のバッファの場合、Emacsはdefault-directoryおよびその親ディレクトリ内でディレクトリローカル変数を検索します。
この関数は、シンボルである指定の class
に対する一連の変数設定を定義します。後でこのクラスを1つ以上のディレクトリに割り当てると、Emacs
はそれらのディレクトリ内のすべてのファイルにこれらの変数設定を適用します。variables
のリストは、(major-mode . alist) または (directory . list)
のいずれかの形式をとります。前者の形式では、ファイルのバッファが major-mode
から派生したモードに切り替わった場合、関連する alist 内のすべての変数が適用されます。alist は (name
. value) の形式である必要があります。major-mode に特別な値 nil
を指定すると、設定があらゆるモードに適用されることを意味します。alist では、特別な name: subdirs を使用できます。関連する値が
nil の場合、このalist
は該当するディレクトリ内のファイルにのみ適用され、サブディレクトリ内のファイルには適用されません。
variables の2番目の形式において、directory がファイルのディレクトリの先頭部分文字列である場合、list は上記の規則に従って再帰的に適用されます。list は、variables においてこの関数が受け付ける2つの形式のいずれかである必要があります。
この関数は、directoryおよびそのサブディレクトリ内のすべてのファイルにclassを割り当てます。その後、classで指定されたすべての変数設定が、directoryおよびその配下にある閲覧済みのあらゆるファイルに適用されます。classは、あらかじめdir-locals-set-class-variablesによって定義されている必要があります。
Emacsは、.dir-locals.el
ファイルからディレクトリ変数を読み込む際、内部的にこの関数を使用します。その場合、オプション引数 mtime にはファイルの更新日時（file-attributes
によって返される値）が格納されます。Emacsはこの時刻を用いて、保存されているローカル変数が依然として有効であるかを確認します。ファイル経由ではなくクラスを直接代入する場合は、この引数を
nil とする必要があります。
このalistには、クラスシンボルとそれに関連付けられた変数設定が格納されています。dir-locals-set-class-variablesによって更新されます。
このalistには、ディレクトリ名、割り当てられたクラス名、および関連するディレクトリローカル変数ファイル（存在する場合）の更新日時が格納されています。関数
dir-locals-set-directory-class はこのリストを更新します。
このバッファローカル変数には、ディレクトリローカル変数の設定のalistが格納されています。alistの各要素は (var . value) という形式をしており、ここで var
はローカル変数のシンボル、value はその値です（これは file-local-variables-alist と同じ構造です。ファイルローカル変数
を参照してください）。Emacsがファイルを読み込む際、すべてのディレクトリローカル変数をこのalistに収集し、その後 hack-local-variables 関数がそれらを一つずつ適用します（こちらも ファイルローカル変数 を参照してください）。
この専用フックには、特定のバッファで使用するディレクトリローカル変数を収集する関数がまとめられています。デフォルトでは、本節で説明するその他の設定に従う関数のみが含まれています。ただし、他のテキストエディタで使用されるものなど、より多くのディレクトリローカル変数のソースへの対応を追加するために利用することも可能です。
このフックの関数は、バッファのメジャーモード関数が実行された後、ディレクトリローカル変数を適用しようとするバッファに対して、引数なしで呼び出されます。これにより、major-mode や buffer-file-name
といった情報源を利用して、適用すべき変数を特定することができます。
(directory . alist)
形式のコンスセル、またはそのようなコンスセルのリストのいずれかを返す必要があります。戻り値が nil
の場合は、ディレクトリローカル変数が見つからなかったことを意味します。directory
は文字列であり、変数が適用されるディレクトリ名となります。alist
は、現在のバッファに適用される変数とその値のリストであり、各要素は (varname . value) 形式となります。
これらの関数から返される各種 alist は統合され、競合が生じた場合は、ディレクトリ階層において上位のディレクトリよりも深いディレクトリにある設定が優先されます。最後に、このフックはファイルにアクセスするたびに実行されるため、これらの関数の効率性を維持するよう努めることが重要であり、通常は何らかのキャッシュ機構が必要となります。
nil
の場合、ディレクトリローカル変数は無視されます。この変数は、ファイルローカル変数は維持しつつディレクトリローカル変数を無視したいモードにおいて有用です（ファイルローカル変数を参照）。