28.2.1 Project Commands That Operate on Files

C-x p f

Visit a file that belongs to the current project ( project-find-file).

C-x p g

Find matches for a regexp in all files that belong to the current project ( project-find-regexp).

M-x project-search

Interactively search for regexp matches in all files that belong to the current project.

C-x p r

Perform query-replace for a regexp in all files that belong to the current project ( project-query-replace-regexp).

C-x p d

Run Dired in the current project’s root directory ( project-dired).

C-x p v

Run vc-dir in the current project’s root directory ( project-vc-dir).

C-x p s

Start an inferior shell in the current project’s root directory ( project-shell).

C-x p e

Start Eshell in the current project’s root directory ( project-eshell).

C-x p c

Run compilation in the current project’s root directory ( project-compile).

C-x p !

Run shell command in the current project’s root directory ( project-shell-command).

C-x p &

Run shell command asynchronously in the current project’s root directory ( project-async-shell-command).

Emacs provides commands for handling project files conveniently. This subsection 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.

The command C-x p f ( project-find-file) is a convenient way of visiting files (see Visiting Files) 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 first element of the “future history”.

The command C-x p g ( project-find-regexp) is similar to rgrep (see Searching with Grep under Emacs), 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 Commands Available in the *xref* Buffer). 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. The way this command displays the matches is affected by the value of xref-auto-jump-to-first-xref (see Searching and Replacing with Identifiers).

M-x project-search is a sequential 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.

C-x p r ( 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.

The command C-x p d ( project-find-dir) prompts you to choose a directory inside the current project, with completion. And opens a Dired buffer (see Dired, the Directory Editor) listing the files in it.

The command C-x p D ( project-dired) opens a Dired buffer (see Dired, the Directory Editor) listing the files in the current project’s root directory.

The command C-x p v ( project-vc-dir) opens a VC Directory buffer (see VC Directory Mode) listing the version control statuses of the files in a directory tree under the current project’s root directory.

The command C-x p s ( project-shell) starts a shell session (see Running Shell Commands from Emacs) in a new buffer with the current project’s root as the working directory.

The command C-x p e ( project-eshell) starts an Eshell session in a new buffer with the current project’s root as the working directory. See Eshell in Eshell: The Emacs Shell.

The command C-x p c ( project-compile) runs compilation (see Running Compilations under Emacs) in the current project’s root directory.

The command C-x p ! ( project-shell-command) runs shell-command in the current project’s root directory.

The command C-x p & ( project-async-shell-command) runs async-shell-command in the current project’s root directory.