Projects

One of the main goals of Projectile is to operate on a wide range of project types without the need for any configuration. To achieve this it contains a lot of project detection logic and project type specific logic.

Broadly speaking, Projectile identifies projects like this:

While Projectile aims to recognize most project types out-of-the-box, it’s also extremely flexible configuration-wise, and you can easily alter the project detection logic.

If a project you are working on is recognized incorrectly or you want to add your own type of projects you can add following to your Emacs initialization code

What this does is:

Let’s see a couple of more complex examples.

This example uses projectile-dotnet-project-p to validate the project’s structure. Since C# and F# project files have names containing the name of the project, it uses a list of wildcards to specify the different valid project-file name patterns.

All those projects are using Gemfile (bundler's project file), but they have different directory structures.

Below is a listing of all the available options for projectile-register-project-type:

You can also pass a symbolic reference to a function into your project type definition if you wish to define the compile command dynamically:

If you would now navigate to a file that has the *.java extension under the ./tests/ directory and hit C-c c p you will see ./gradlew build as the suggestion. If you were to navigate to a HTML file the compile command will have switched to ./gradlew compile-templates.

This works for:

Note that your function has to return a string to work properly.

Project detection is pretty simple - Projectile just runs a list of project detection functions (projectile-project-root-functions) until one of them returns a project directory.

This list of functions is customizable, and while Projectile has some defaults for it, you can tweak it however you see fit.

Let’s take a closer look at projectile-project-root-functions:

The important thing to note here is that the functions get invoked in their order on the list, so the functions earlier in the list will have a higher precedence with respect to project detection. Let’s examine the defaults:

The default ordering should work well for most people, but depending on the structure of your project you might want to tweak it.

Re-ordering those functions will alter the project detection, but you can also replace the list. Here’s how you can delegate the project detection to Emacs’s built-in function vc-root-dir:

Similarly, you can leverage the built-in project.el like this:

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. Alternatively, not having any prefix at all also means to ignore the directory or file pattern that follows. 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 would like to include comment lines in your .projectile file, you can customize the variable projectile-dirconfig-comment-prefix. Assigning it a non-nil character value, e.g. #, will cause lines in the .projectile file starting with that character to be treated as comments instead of patterns.

From project to project, some things may differ even in the same language - coding styles, auto-completion sources, etc. If you need to set some variables according to the selected project, you can use a standard Emacs feature called Per-directory Local Variables. To use it you must create a file named .dir-locals.el (as specified by the constant dir-locals-file) inside the project directory. This file should contain something like this:

The top-level alist member referenced with the key nil applies to the entire project. A key with the name eval will evaluate its corresponding value. In the example above, this is used to create a function. It could also be used to e.g. add such a function to a key map.

Here are a few examples of how to use this feature with Projectile.

Projectile exposes many variables (via defcustom) which allow users to customize its behavior. Directory variables can be used to set these customizations on a per-project basis.

You could enable caching for a project in this way:

If one of your projects had a file that you wanted Projectile to ignore, you would customize Projectile by:

If you wanted to wrap the git command that Projectile uses to list the files in you repository, you could do:

If you want to use a different project name than how Projectile named your project, you could customize it with the following:

By default, compilation buffers are not writable, which allows you to e.g. press g to restart the last command. Setting projectile-<cmd>-use-comint-mode (where <cmd> is configure, compile, test, install, package, or run) to a non-nil value allows you to make projectile compilation buffers interactive, letting you e.g. test a command-line program with projectile-run-project.

Projectile offers a bunch of operations that are operating on the open buffers for some project (e.g. projectile-kill-buffers). One tricky part here are "special buffers" - basically buffers that are not backed by files (e.g. *dired*, +scratch+ and so on). Projectile determines whether a special buffer belongs to a project simply by checking the default-directory for the special buffer, which admittedly might result in some weird results (e.g. if you’ve created a special buffer that’s not related to a project, while visiting a file belonging to the project).

That’s why Projectile has a couple of configuration options for dealing with project buffers - namely projectile-globally-ignored-buffers and projectile-globally-ignored-modes. Both of them take a list of strings or regular expressions that will be used to match against a buffer’s name or a buffer’s major mode.

Here are a couple of examples:

There are a few variables that are intended to be customized via .dir-locals.el.

When these variables have their default value of nil, Projectile runs the default command for the current project type. You can override this behavior by setting them to either a string to run an external command or an Emacs Lisp function:

In addition caching of commands can be disabled by setting the variable projectile-project-enable-cmd-caching is to nil. This is useful for preset-based CMake projects.

By default, Projectile will not add consecutive duplicate commands to its command history. To alter this behaviour you can use projectile-cmd-hist-ignoredups. The default value of t means consecutive duplicates are ignore, a value of nil means nothing is ignored, and a value of 'erase' means only the last duplicate is kept in the command history.