Projects

Projectile considers most version-controlled repos to be a project. Out of the box Projectile supports:

Projectile considers many files to denote the root of a project. Usually those files are the configuration files of various build tools. Out of the box the following are supported:

There’s also Projectile’s own .projectile which serves both as a project marker and a configuration file. We’ll talk more about later in this section.

The :test-prefix and :test-suffix will work regardless of file extension or directory path and should be enough for simple projects. The projectile-other-file-alist variable can also be set to find other files based on the extension.

For fine-grained control of implementation/test toggling, the :test-dir option of a project may take a function of one parameter (the implementation directory absolute path) and return the directory of the test file. This in conjunction with the options :test-prefix and :test-suffix will then be used to determine the full path of the test file. This option will always be respected if it is set.

Similarly, the :src-dir option, the analogue of :test-dir, may also take a function and exhibits exactly the same behaviour as above except that its parameter corresponds to the directory of a test file and it should return the directory of the corresponding implementation file.

It’s recommended that either both or neither of these options are set to functions for consistent behaviour.

Alternatively, for flexible file switching across a range of projects, the :related-files-fn option set to a custom function or a list of custom functions can be used. The custom function accepts the relative file name from the project root and it should return related file information as a plist with the following optional key/value pairs:

For each value, following type can be used:

Notes:

:related-files-fn can accept a list of custom functions to combine the result of each custom function. This allows users to write several custom functions and apply them differently to projects.

Projectile includes a couple of helpers to generate commonly used custom functions.

Each helper means projectile-related-files-fn-helper-name function.

You can also edit specific options of already existing project types:

This will change the value of the related-files-fn option, remove the test-prefix option and :precedence 'high sets the sbt project type to be chosen in preference to other potentially clashing project types (a value 'low would do the opposite).

If a built-in project type mis-detects your projects (e.g. a language manifest that also appears in subdirectories of a larger repo), you can unregister it entirely:

Whilst setting the :test-dir and :src-dir to strings is sufficient for most purposes, using functions can give more flexibility. As an example consider (also using f.el):

This attempts to recognise projects using both test and tests as top level directories for test files. An alternative using the related-files-fn option could be:

In fact this is a lot more flexible in terms of finding test files in different locations, but will not create test files for you.

When a project type doesn’t specify :src-dir or :test-dir, Projectile falls back to these defaults:

For advanced use cases you can replace the functions that determine the test file prefix and suffix. These receive the project type and should return the appropriate prefix or suffix string:

By default, when you toggle to a test file that doesn’t exist, Projectile will signal an error. If you’d like Projectile to create the missing test file automatically:

To keep projectile-project-root cheap (it’s called from the mode-line and several find-file-hook paths), Projectile memoizes the result of every project root function in the variable projectile-project-root-cache. The cache is populated lazily and only invalidated when:

The cache is keyed on the search start directory and a positive entry is revalidated against the filesystem (via file-exists-p) on every lookup, so a deleted root naturally invalidates itself. Negative entries (no project found) are also memoized to avoid re-walking the directory tree on every call; this is the main source of confusion when adding a marker file: Projectile remembers that the directory was rootless and won’t notice the new marker until you invalidate the cache.

If you frequently script Projectile from elisp and need finer-grained control, you can clear individual entries with remhash against the cache, or reset the whole thing with (setq projectile-project-root-cache (make-hash-table :test 'equal)).

If you’d like to instruct Projectile to ignore certain files in a project, when indexing it you can do so in the .projectile file by adding each path to ignore, where the paths all are relative to the root directory and start with a slash. Everything ignored should be preceded with a - sign.

Here’s an example for a typical Rails application:

This would ignore the folders only at the root of the project. Projectile also supports relative pathname ignores:

You can also ignore everything except certain subdirectories. This is useful when selecting the directories to keep is easier than selecting the directories to ignore, although you can do both. To select directories to keep, that means everything else will be ignored.

Example:

Keep in mind that you can only include subdirectories, not file patterns.

If both directories to keep and ignore are specified, the directories to keep first apply, restricting what files are considered. The paths and patterns to ignore are then applied to that set.

Finally, you can override ignored files. This is especially useful when some files ignored by your VCS should be considered as part of your project by projectile:

When a path is overridden, its contents are still subject to ignore patterns. To override those files as well, specify their full path with a bang prefix.

If you’re using the hybrid or alien indexing strategies, the simplest way to ignore some files is just leverage the configuration of the tool you’re using to do the project indexing.

E.g. in the case of git you can just tweak .gitignore.

Sometimes, however, you’d like to have some files as part of your project, but you don’t want to see them in Projectile for whatever reasons.

In those cases the project dirconfig file (.projectile) can be a handy way to further adjust what you want to see in Projectile.

In addition to per-project ignores, Projectile provides several variables for globally ignoring files and directories. These take effect with native and hybrid indexing but are not applied with the alien indexing method.

You can supply a custom filter function for projectile-project-buffers via projectile-buffers-filter-function. Projectile ships with two built-in filters you can use:

When you run projectile-kill-buffers (s-p k), the variable projectile-kill-buffers-filter controls which buffers get killed:

You can also set it to a custom predicate function that receives a buffer and returns non-nil if the buffer should be killed.

For finer control there’s a small composable condition DSL (modeled on project.el’s `project-kill-buffer-conditions). Set the filter to a list of conditions and a buffer is killed when it matches any of them:

Each condition is a buffer-name regexp, a predicate function, or a cons cell: (major-mode . MODE), (derived-mode . MODE), (not COND), (and COND…​), or (or COND…​). The last three nest, so you can build arbitrarily specific rules. See the docstring of projectile-kill-buffers-filter for the details.

When you open same-named files from different projects (say two README.md files), Emacs’s uniquify library disambiguates the buffer names using parent directory components. Projectile can make that disambiguation use the project name instead, via projectile-uniquify-dirname-transform:

Outside of a project the directory is left untouched, so this is safe to set globally. This mirrors project.el’s `project-uniquify-dirname-transform.