Home

Awesome

dir-config.el - Automatically find and evaluate .dir-config.el Elisp files (Flexible dir-locals alternative)

MELPA Build Status

The dir-config Emacs package automatically loads and evaluates Elisp code from a .dir-config.el file found in the buffer's current directory or its closest parent directory. This facilitates adjusting settings or executing functions specific to the directory structure of each buffer.

For instance, you can use the dir-config package to:

Features:

Installation

Install with straight

To install dir-config from MELPA:

  1. If you haven't already done so, add MELPA repository to your Emacs configuration.

  2. Add the following code to your Emacs init file to install dir-config from MELPA:

(use-package dir-config
  :ensure t
  :custom
  (dir-config-file-names '(".dir-config.el"))
  (dir-config-allowed-directories '("~/src" "~/projects"))
  :config
  (dir-config-mode))

Note:

Example usage

Assuming that the dir-config package has been configured to allow loading configuration files from specific directories, such as ~/src, by setting the dir-config-allowed-directories variable:

(setq dir-config-allowed-directories '("~/src" "~/projects"))

Adding the following code to the ~/src/my_python_project/.dir-config.el file can modify the PYTHONPATH environment variable for Python buffers within its directory or one of its subdirectories (e.g., ~/src/my_python_project/my_python_project/file.py). Modifying PYTHONPATH ensures that processes executed by tools like Flycheck or Flymake have access to the Python project's modules:

;;; .dir-config.el --- Directory config -*- no-byte-compile: t; lexical-binding: t; -*-
(when (or (derived-mode-p 'python-ts-mode) (derived-mode-p 'python-mode))
  (let ((python-path (getenv "PYTHONPATH"))
        (dir (dir-config-get-dir)))
    ;; Update the PYTHONPATH environment variable to ensure that Flycheck,
    ;; Flymake, and other subprocesses can locate the Python modules.
    (when (and dir (or (file-exists-p (expand-file-name "setup.py" dir))
                       (file-exists-p (expand-file-name "pyproject.toml" dir))))
      (setq-local process-environment (copy-sequence process-environment))
      (setenv "PYTHONPATH" (concat dir (when python-path (concat ":" python-path)))))))

It is recommended to always begin your .dir-config.el files with the following header:

;;; .dir-config.el --- Directory config -*- no-byte-compile: t; lexical-binding: t; -*-

The dir-config package allows for automatic application of specific configurations based on the directory of the files being accessed, enhancing the flexibility and customization of the Emacs environment.

Frequently Asked Questions

How does .dir-config.el files compare to .dir-locals.el?

Here is the difference between with .dir-locals.el and the .dir-config.el files:

Wouldn't it be better to move .dir-config.el Elisp code into Emacs init?

Dir config files (.dir-config.el) offer advantages for managing complex directory-specific configurations that require dynamic logic. They allow projects or directories to define their needs, providing flexibility to customize configurations to specific requirements.

For example, one of the author's use cases is to use dir-config.el to enable Emacs features only in trusted directories while keeping these features disabled by default (for security reasons, some code linters need to be disabled by default because they evaluate code).

While this code could be included in the author's init file, he prefers to keep the init file as a general editor configuration without project-specific details. Since the author uses multiple machines for various purposes, he finds it more straightforward to let the filesystem hierarchy (e.g., a Git repository or a project directory) determine the specific settings for each directory or project using .dir-config.el.

License

Copyright (C) 2023-2024 James Cherti

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program.

Links

Other Emacs packages by the same author: