Configuration

The alien indexing works in a pretty simple manner - it simply shells out to a command that returns the list of files within a project. For version-controlled projects by default Projectile will use the VCS itself to obtain the list of files. As an example, here is the command that Projectile uses for Git projects:

For every supported VCS there’s a matching Projectile defcustom holding the command to invoke for it:

There are also two Git-specific commands for listing submodules and ignored files:

For non-VCS projects Projectile will invoke whatever is in projectile-generic-command. The default chooses fd when it’s installed and falls back to find:

By default, fd is also used inside Git repositories (instead of git ls-files), because git ls-files has the limitation that it lists deleted files until the deletions are staged. With fd, deleted files disappear from the listing immediately; with git ls-files, Projectile post-filters the listing against git ls-files -zd to hide deletions until they’re staged. You can control this with projectile-git-use-fd:

You can also customize the path to the fd executable and the arguments passed to it:

The hybrid method runs the same external command as alien and then post-processes the result with Projectile’s filtering rules. In other words, it’s alien plus a second pass that applies:

This is the right choice when your VCS lists more files than you want Projectile to surface (e.g. you want to drop *.elc even though they’re checked in), or when you rely on .projectile to keep/ignore subtrees inside an otherwise large repository. It’s slower than alien because of the extra pass, but it remains substantially faster than native for big projects since the file list itself is still produced by the external tool.

Not all Projectile features apply to every indexing method. The table below summarises which configuration knobs take effect under which mode:

Since indexing a big project is not exactly quick (especially in Emacs Lisp), Projectile supports caching of the project’s files. The caching is enabled by default whenever native indexing is enabled.

To enable caching unconditionally use this snippet of code:

At this point you can try out a Projectile command such as s-p f (M-x projectile-find-file RET).

Running C-u s-p f will invalidate the cache prior to prompting you for a file to jump to.

Pressing s-p z will add the currently visited file to the cache for current project. Generally files created outside Emacs will be added to the cache automatically the first time you open them.

Normally the cache lasts for the duration of your Emacs session. If you want to cache to persist between Emacs sessions you should set this option to 'persistent.

Now the project cache is persistent and will be preserved during Emacs restarts. Each project gets its own cache file, that will be placed in the root folder of the project. The name of the cache file is .projectile-cache.eld by default, but you can tweak it if you want to:

The cache file will be loaded automatically in memory the first time you trigger a "find file" operation for the project it belongs to.

You can purge an individual file from the cache with M-x projectile-purge-file-from-cache or an entire directory with M-x projectile-purge-dir-from-cache.

When projectile-mode is enabled Projectile will auto-update the project cache when files within are added or deleted from within Emacs. (this is achieved by file hooks) This behavior can be disabled like this:

You can also set the project files cache to expire after a given number of seconds:

By default projectile-files-cache-expire is nil, meaning the cache never expires automatically.

One last thing - the project cache will be auto-invalidated if you’re using .projectile and it’s last modification time is more recent than the time at which the cache file was last updated.

The first "find file" in a large or remote project has to index it. With the alien and hybrid indexing methods Projectile does this without freezing Emacs: the indexing command runs asynchronously and is awaited in a way that keeps redisplay going and leaves C-g live, so you can abort a slow index (for instance one stuck on an unresponsive remote host) instead of staring at a frozen editor. The resulting file list is exactly what the synchronous indexer would produce.

This is on by default and controlled by projectile-async-indexing:

You can also warm the cache ahead of time, without blocking, using M-x projectile-index-project-async:

It runs the project’s indexing command via an asynchronous process and populates the same cache that a regular projectile-find-file reads, so a later "find file" finds the cache already warm instead of indexing on the spot. You could, for instance, warm a project right after switching to it:

The asynchronous building blocks it’s made of - projectile-files-via-ext-command-async and projectile-dir-files-alien-async - are public, so a streaming file finder (for example one built on top of consult) can drive Projectile’s indexing command asynchronously and feed results into its own UI. See the next section.

If you’d rather have your own asynchronous/streaming UI (à la fzf, consult or affe) list a project’s files instead of projectile-find-file, projectile-project-files-producer hands you everything you need to run Projectile’s own indexing command yourself:

Run :command in :directory and split its output on :separator. A minimal (non-streaming) example built on the public asynchronous runner:

A real streaming finder would instead consume the process output incrementally (filtering as you type) rather than collecting it. For git projects, note that :command lists the main worktree only; if you want byte-for-byte the same set as projectile-find-file (submodule files folded in, deleted-but-unstaged files removed) drive projectile-dir-files-alien-async instead.

Projectile does many file existence checks since that is how it identifies a project root. Normally this is fine, however in some situations the file system speed is much slower than usual and can make emacs "freeze" for extended periods of time when opening files and browsing directories.

The most common example would be interfacing with remote systems using TRAMP/ssh. By default all remote file existence checks are cached

To disable remote file exists cache that use this snippet of code:

To change the remote file exists cache expire to 10 minutes use this snippet of code:

You can also enable the cache for local file systems, that is normally not needed but possible:

With this setting, once you have selected your project via Projectile’s completion system (see below), you will remain in the completion system to select a file to visit. projectile-find-file is capable of retrieving files in all sub-projects under the project root, such as Git submodules. Currently, only Git is supported. Support for other VCS will be added in the future.

If you often need to invoke a different action right after switching to a project, press C-u s-p p (a prefix argument to any switch-project command). After you pick a project, Projectile opens the projectile-dispatch menu so you can choose what to do in it.

Similar to projectile-find-file but lists all files in all known projects. Since the total number of files could be huge, it is beneficial to enable caching for subsequent usages.

If point is on a filepath, Projectile first tries to search for that file in project:

With this setting, once you have selected your project, the top-level directory of the project is immediately opened for you in a dired buffer.

With this setting, once you have selected your project, you will remain in Projectile’s completion system to select a sub-directory of your project, and then that sub-directory is opened for you in a dired buffer. If you use this setting, then you will probably also want to set

in order to allow for the occasions where you want to select the top-level directory.

You can prevent certain projects from being added to the known projects list:

For more flexible filtering, set projectile-ignored-project-function to a predicate that receives a project root and returns non-nil if the project should be ignored:

By default, Projectile automatically adds projects to the known projects list whenever you visit a file in a project. You can disable this:

You can also set projectile-completion-system to a function that accepts a prompt and a list of choices:

An example of a custom completion function is this one, which only shows the file name (not including path) and, if the selected file is not unique, follows up with a completion over names relative to the project root.

Register a backend with projectile-register-search-backend. It takes a name, a :description, an optional :available predicate, and a :search function called with the search term and a flag indicating whether it’s a regexp. For example, to add deadgrep:

By default Projectile echoes informational messages (not just errors). To suppress them:

Projectile adds a menu to the Emacs menu bar by default. To disable it:

Projectile supports CMake presets. Preset support is disabled by default, but can be enabled by setting projectile-enable-cmake-presets to non-nil. With preset-support enabled Projectile will parse the preset files and present the command-specific presets when executing a lifecycle command. In addition a no preset option is included for entering the command manually.