Usage

Here’s how a typical Projectile configuration would look:

The example above builds upon the simpler setup demonstrated in the "Installation" section.

To add a project to Projectile’s list of known projects, open a file in the project. If you have a projects directory, you can tell Projectile about all of the projects in it with the command M-x projectile-discover-projects-in-directory.

You can go one step further and set a list of folders which Projectile is automatically going to check for projects on startup.

Recursive discovery is configured by specifying the search depth in a cons cell:

Automatic discovery is controlled by projectile-auto-discover, which is enabled by default. The search path is scanned the first time a project-switching command runs in an Emacs session (not on every switch), so pointing projectile-project-search-path at your projects directory is all you need. To turn the automatic scan off:

You can always trigger a fresh scan manually with M-x projectile-discover-projects-in-search-path.

From time to time you’ll have projects in your list of known projects that are no longer around. (e.g. they were removed or renamed) You can either trigger the command projectile-cleanup-known-projects manually or set the variable projectile-auto-cleanup-known-projects to t to remove such projects automatically.

projectile-cleanup-known-projects is also available under the alias projectile-forget-zombie-projects, if you’re used to that name from project.el.

To drop a whole group of known projects at once (e.g. after deleting a directory that held several checkouts) use projectile-forget-projects-under. It prompts for a directory and removes the known projects that live directly under it; with a prefix argument it also removes projects nested deeper in the tree.

Projectile reads through Emacs’s built-in completing-read, so it works with whatever minibuffer UI you use. It works fine with the stock completion, but you’re encouraged to pair it with a modern package like vertico (+ consult, marginalia, orderless) or fido-mode/fido-vertical-mode. See A recommended setup for the combination this manual assumes, and the surrounding Completion Options section for the rest, including how to plug in a custom completion function.

Projectile will work without any external dependencies out of the box. However, if you have various tools installed, they will be automatically used when appropriate to improve performance.

Inside version control repositories, VC tools are used when installed to list files more efficiently. The supported tools include git, hg, fossil, bzr, darcs, pijul, svn, sapling and jujutsu.

Outside version control repositories, file search tools are used when installed for a faster search than pure Elisp. The supported tools include fd and GNU/BSD find.

By default, if fd is installed, it is also used inside Git repositories as an alternative to git ls-files, because git ls-files has the limitation that it also lists deleted files until the deletions are staged, which can be confusing. You can eliminate the use of fd in this circumstance by setting projectile-git-use-fd to nil.

To benefit from the projectile-ag and projectile-ripgrep commands to perform file search, it’s recommended to install ag (the_silver_searcher) and/or rg (ripgrep)

projectile-replace (s-p r) and projectile-replace-regexp run a blocking, file-by-file query-replace walk with no preview. When you’d rather see every match up front and pick which ones to apply, use the reviewable replace commands instead:

Both prompt for the search term and the replacement, then gather all the matches across the project into a *projectile-replace* buffer. Matches are collected in Emacs Lisp rather than via an external grep, so the regexp command honors full Emacs regexp syntax (e.g. symbol boundaries like _<foo\_>) and the preview reflects the exact text that will be edited, including any unsaved changes in already-open buffers.

Here’s the whole flow - gather the matches, toggle off the ones you want to keep, apply the rest:

Every match starts enabled (shown as [X]); toggle the ones you don’t want off ([ ]) and apply only the rest, in any order. The results buffer supports these keys:

A status line at the top of the buffer shows the term, the replacement, the match and file counts, the active mode flags ([literal]/[regexp] and [case-sensitive]/[ignore-case]), and a filtered note once you’ve pruned the list.

You can reshape the search without leaving the buffer. c toggles case sensitivity (seeded from case-fold-search) and x toggles literal versus Emacs-regexp matching, each re-scanning and re-rendering the previews in place; switching to regexp mode with a term that isn’t a valid regexp is refused with a message rather than erroring. Because a toggle re-scans from scratch, it rebuilds the match list and every match comes back enabled, so any per-match include/exclude toggles you had set are reset (use the filter keys instead to prune while keeping the survivors' state). The filter keys narrow the shown matches, either by the match’s line (k keep, d flush) or by its project-relative file name (K keep, D flush). Filtering only hides matches from the current list; re-running the search (g) gathers from scratch and brings them back.

Applying edits a file’s matches from the bottom up so earlier edits don’t disturb later ones, edits already-open buffers in place under a single undo step (and saves them), and writes closed files back to disk preserving their coding system. A buffer that was modified after the search is skipped rather than risk a bad edit; re-run the search (g) to pick up its current state. Very large searches are capped at projectile-replace-max-matches.

The project is scanned asynchronously: the *projectile-replace* buffer opens right away and matches stream in as they are found (the status line shows a Searching…​ note with the running count), so a large search never freezes Emacs. The scan is cancelable with q, C-g, or by killing the buffer. While it is still running, ! and e refuse until it finishes, so the write-back never runs against a partial match set; starting a new scan (g, c, x) first cancels any in-flight one. Set projectile-replace-async to nil to force the old synchronous single-pass scan instead; batch (noninteractive) runs always scan synchronously.

! applies the enabled matches with no external dependency. If you’d rather edit the results as text, e exports the enabled matches (the same set ! would act on) to a *projectile-grep* buffer in grep-mode, with standard RELPATH:LINE:CONTEXT lines navigable with next-error and RET. This is the bridge to wgrep (C-c C-p to make it editable, then C-c C-c to write back) or Emacs 31’s grep-edit-mode. wgrep is an optional integration, not a dependency; after exporting, Projectile tells you which workflow is available based on what you have installed.

When you want to look through every match for a term across the project without changing anything, the search reviewer is the read-only sibling of the replace reviewer:

Both prompt only for the search term (defaulting to the symbol or region at point) and gather every match into a read-only *projectile-search* buffer, grouped by file, one LINE:COL: CONTEXT line per match with the matched span highlighted. There is no replacement, no per-match toggle and no apply: the buffer never edits your files.

The results buffer supports these keys:

The status line, the case/regexp toggles, the filter keys, the grep export and the asynchronous, cancelable scanning (including projectile-replace-async) behave exactly as in the replace reviewer above; only the preview, per-match toggle and apply are absent. r is the search-to-replace bridge: it carries over the same term, literal-ness and case setting and opens the *projectile-replace* reviewer, prompting only for the replacement. It re-runs the search from scratch, so any filtering you did in the search buffer is not carried into the replacement. Very large searches are capped at projectile-replace-max-matches.

When projectile-search-use-ripgrep is non-nil (the default) and the rg (ripgrep) executable is installed, a literal projectile-search-review scan runs through ripgrep instead of the pure-Emacs-Lisp scan, which returns near-instantly even on a large project; the matches stream into the same read-only buffer and every reviewer command works unchanged. The ripgrep fast-path follows ripgrep’s own ignore rules (.gitignore, .ignore, hidden-file handling, and so on) plus Projectile’s ignore globs (.projectile and the globally-ignored files and directories, passed to rg via --glob), which can differ slightly from the pure-elisp path’s file set (for example in how hidden files or symlinks are treated). Matches in files that aren’t valid UTF-8 are also skipped by the ripgrep path but found by the elisp path. This is an accepted trade-off for speed; set projectile-search-use-ripgrep to nil to force the elisp scan, whose result set matches Projectile’s ignore configuration exactly. The regexp search command always uses the elisp scan (ripgrep’s regex syntax is not Emacs regexp syntax), and the whole replace reviewer always uses the elisp scan (its write-back needs the exact buffer positions the elisp scan records). The one exception is projectile-todos below: it builds its own pattern and hands the reviewer a ripgrep-syntax spelling of it, so it gets the fast-path despite not being a literal search.

projectile-todos (s-p s t) gathers every TODO/FIXME-style annotation in the project into the same read-only *projectile-search* buffer, so all the keys in the table above apply - navigate them, filter them down with k/d/K/D, export them to grep-mode, or hand them to the replace reviewer.

The keywords are projectile-todo-keywords, which defaults to:

Add your own conventions to that list (REVIEW, OPTIMIZE, DEPRECATED, …​). With a prefix argument (C-u s-p s t) Projectile prompts for which of the keywords to search for; several can be given, comma separated, and you can type in a keyword that isn’t in the list for a one-off search.

A keyword only counts when it stands as a whole word followed by a colon, by a space or tab, or by the end of the line - so TODO: and FIXME ` are found while `TODOS and MASTODON are not. Matching is case-sensitive, since annotation keywords are uppercase by convention; c in the results buffer relaxes that. The keyword does not have to sit in a comment: neither scan parses the language (and the comment syntax would have to be guessed per file type), so an annotation inside a string or in prose is reported too - d flushes those you don’t care about.

There are two ways to tell whether a bookmark is the project’s, and neither is perfect:

By default Projectile applies both and a bookmark belongs to the project when either test says so. Set projectile-bookmark-scope to file or name to use just one of them:

The menu’s Modifiers group holds switches that tweak how the commands run. Toggle one (or more), then trigger a command:

For example, toggle -d until it shows frame and then press f to find a file and show it in a new frame; or press -i then f to invalidate the cache and find a file. This replaces the old dedicated "other window" and "other frame" menu columns.