File: project.el.html
This file contains generic infrastructure for dealing with projects, some utility functions, and commands using that infrastructure.
The goal is to make it easier for Lisp programs to operate on the current project, without having to know which package handles detection of that project type, parsing its config files, etc.
This file consists of following parts:
Infrastructure (the public API):
Function project-current that returns the current project
instance based on the value of the hook project-find-functions,
and several generic functions that act on it.
project-root must be defined for every project.
project-files can be overridden for performance purposes.
project-ignores and project-external-roots describe the project
files and its relations to external directories. project-files
should be consistent with project-ignores.
project-buffers can be overridden if the project has some unusual
shape (e.g. it contains files residing outside of its root, or some
files inside the root must not be considered a part of it). It
should be consistent with project-files.
This list can change in future versions.
Transient project:
An instance of this type can be returned by project-current if no
project was detected automatically, and the user had to pick a
directory manually. The fileset it describes is the whole
directory, with the exception of some standard ignored files and
directories. This type has little purpose otherwise, as the only
generic function it provides an override for is project-root.
VC-aware project:
Originally conceived as an example implementation, now it's a
relatively fast backend that delegates to 'git ls-files' or 'hg
status' to list the project's files. It honors the VC ignore
files, but supports additions to the list using the user option
project-vc-ignores (usually through .dir-locals.el). See the
customization group project-vc for other options that control its
behavior.
The file listing uses the VC backend function project-list-files.
If the current VC backend does not implement it, the default
mechanism based on find-program is used as fallback.
project-list-files (dir extra-ignores)
DIR is a directory inside the repository.
EXTRA-IGNORES is a list of globs in the format of project-ignores.
This project type can also be used for non-VCS controlled
directories, see the variable project-vc-extra-root-markers.
Utils:
project-combine-directories and project-subtract-directories,
mainly for use in the abovementioned generics' implementations.
project-known-project-roots and project-remember-project to
interact with the "known projects" list.
Commands:
project-prefix-map contains the full list of commands defined in
this package. This map uses the prefix C-x p by default.
Type C-x p f to find file in the current project.
Type C-x p C-h to see all available commands and bindings.
All commands defined in this package are implemented using the public API only. As a result, they will work with any project backend that follows the protocol.
Any third-party code that wants to use this package should likewise target the public API. Use any of the built-in commands as the example.
How to create a new backend:
- Consider whether you really should, or whether there are other
ways to reach your goals. If the backend's performance is
significantly lower than that of the built-in one, and it's first
in the list, it will affect all commands that use it. Unless you
are going to be using it only yourself or in special circumstances,
you will probably want it to be fast, and it's unlikely to be a
trivial endeavor. project-files is the method to optimize (the
default implementation gets slower the more files the directory
has, and the longer the list of ignores is).
- Choose the format of the value that represents a project for your
backend (we call it project instance). Don't use any of the
formats from other backends. The format can be arbitrary, as long
as the datatype is something cl-defmethod can dispatch on. The
value should be stable (when compared with equal) across
invocations, meaning calls to that function from buffers belonging
to the same project should return equal values.
- Write a new function that will determine the current project
based on the directory and add it to project-find-functions
(which see) using add-hook. It is a good idea to depend on the
directory only, and not on the current major mode, for example.
Because the usual expectation is that all files in the directory
belong to the same project (even if some/most of them are ignored).
- Define new methods for some or all generic functions for this
backend using cl-defmethod. A project-root method is
mandatory, project-files is recommended, the rest are optional.
Defined variables (32)
project--list | List structure containing root directories of known projects. |
project-buffers-viewer | Function to use in ‘project-list-buffers’ to render the list. |
project-compilation-buffer-name-function | Function to compute the name of a project compilation buffer. |
project-current-directory-override | Value to use instead of ‘default-directory’ when detecting the project. |
project-current-inhibit-prompt | Value to use instead of ‘default-directory’ when detecting the project. |
project-file-history-behavior | If ‘relativize’, entries in ‘file-name-history’ are adjusted. |
project-files-relative-names | If non-nil, ‘project-files’ is allowed to return relative file names. |
project-find-functions | Special hook to find the project containing a given directory. |
project-find-matching-buffer-function | Function to switch to a matching buffer in another project. |
project-ignore-buffer-conditions | List of conditions to filter the buffers to be switched to. |
project-key-prompt-style | Which presentation to use when asking to choose a command by key. |
project-kill-buffer-conditions | List of conditions to kill buffers related to a project. |
project-kill-buffers-display-buffer-list | Non-nil to display list of buffers to kill before killing project buffers. |
project-list-exclude | Exclude projects from being remembered by ‘project-remember-project’. |
project-list-file | File in which to save the list of known projects. |
project-mode-line | Whether to show current project name and Project menu on the mode line. |
project-mode-line-face | Face name to use for the project name on the mode line. |
project-other-frame-map | Keymap for project commands that display buffers in other frames. |
project-other-window-map | Keymap for project commands that display buffers in other windows. |
project-prefix-map | Keymap for project commands. |
project-prompter | Function to call to prompt for a project. |
project-prune-zombie-projects | Remove automatically from project list the projects that were removed. |
project-read-file-name-function | Function to call to read a file name from a list. |
project-switch-commands | Alist mapping commands to descriptions. |
project-switch-use-entire-map | Whether ‘project-switch-project’ will use the entire ‘project-prefix-map’. |
project-vc-backend-markers-alist | Associative list assigning root markers to VC backend symbols. |
project-vc-external-roots-function | Function that returns a list of external roots. |
project-vc-extra-root-markers | List of additional markers to signal project roots. |
project-vc-ignores | List of patterns to add to ‘project-ignores’. |
project-vc-include-untracked | When non-nil, the VC-aware project backend includes untracked files. |
project-vc-merge-submodules | Non-nil to consider submodules part of the parent project. |
project-vc-name | When non-nil, the name of the current VC-aware project. |