A project is a collection of files used for producing one or more programs. Files that belong to a project are typically stored in a hierarchy of directories; the top-level directory of the hierarchy is known as the project root.
Whether a given directory is a root of some project is determined by the project-specific infrastructure, known as project back-end. Emacs currently supports two such back-ends: VC (see Version Control), whereby a VCS repository is considered a project; and EDE (see EDE). This is expected to be extended in the future to support additional types of projects.
Which files do or don’t belong to a project is also determined by the project back-end. For example, the VC back-end doesn’t consider “ignored” files (see VC Ignore) to be part of the project.
Emacs provides commands for handling project files conveniently. This section describes these commands.
All of the commands described here share the notion of the
current project. The current project is determined by the
default-directory (see File Names) of the buffer that is
the current buffer when the command is invoked. If that directory
doesn’t seem to belong to a recognizable project, these commands
prompt you for the project directory.
project-find-file is a convenient way of visiting
files (see Visiting) that belong to the current project. Unlike
C-x C-f, this command doesn’t require to type the full file name
of the file to visit, you can type only the file’s base name (i.e.,
omit the leading directories). In addition, the completion candidates
considered by the command include only the files belonging to the
current project, and nothing else. If there’s a file name at point,
this command offers that file as the default to visit.
project-find-regexp is similar to
(see Grep Searching), but it searches only the files that belong
to the current project. The command prompts for the regular
expression to search, and pops up an Xref mode buffer with the search
results, where you can select a match using the Xref mode commands
(see Xref Commands). When invoked with a prefix argument, this
command additionally prompts for the base directory from which to
start the search; this allows, for example, to limit the search only
to project files under a certain subdirectory of the project root.
M-x project-search is an interactive variant of
project-find-regexp. It prompts for a regular expression to
search in the current project’s files, but instead of finding all the
matches and displaying them, it stops when it finds a match and visits
the matched file at the locus of the match, allowing you to edit the
matched file. To find the rest of the matches, type M-x fileloop-continue RET.
M-x project-query-replace-regexp is similar to
project-search, but it prompts you for whether to replace each
match it finds, like
query-replace does (see Query Replace), and continues to the next match after you respond. If your
response causes Emacs to exit the query-replace loop, you can later
continue with M-x fileloop-continue RET.