What is Projectile?
Project homepage : http://batsov.com/projectile/
Projectile is a project interaction library for Emacs. It's not a project management package, in that it doesn't handle task lists, gantt charts or things like that.
In practice, Projectile works as a way to limit functionality to files in whatever project is currently being worked on.
Projects are just a directory and its files which makes things simple. By
default Projectile will treat any directory under source control as a project,
but adding a .projectile
file to a directory will also turn it into a project.
The file list can be filtered to ignore entries, either via .gitignore
or in
the .projectile
file.
What can I use it for?
There's some tasks I perform quite often:
- Navigating project files
- Running tests and compilation commands
- Switching between tests and source files
- Switching between controllers and views
- Running grep and occur
And some I do less often:
- Running a shell in a project's directory
- Renaming files within a project
- Jumping to an included file
None of these are particularly time consuming, but I'd still like to streamline them if possible. Let's see if Projectile can help.
Navigating project files
Normally I would use C-x C-f (find-file
) to open other
files in a project. Projectile provides C-c p f
(projectile-find-file
), which is a very fast alternative.

Ignored files are automatically filtered from the list and it integrates nicely with Helm.
C-c p d works in a similar way for directories and opens
them in dired
. C-c p b can be used to switch between
project buffers.
Running tests and compilation commands
For most projects I'll have a terminal window open to run tests and compile code. Both of these things can be done using Projectile commands:
- C-c p P – Runs a test command for the current project.
- C-c p c – Runs a compilation command for the current project.
Each command will try to figure out the best function for the current project type. There are currently 30 different project types built-in, covering Rails, Symfony, Django and a bunch of other common platforms.
Project types are assigned by searching for specific files in the project
root. For example, finding a Makefile
file in the root will set the default
compile command to make
and the default test command to make test
.
Projects can set their compile and test commands using Emacs .dir-locals.el
.
projectile-project-compilation-cmd
sets the compilation commandprojectile-project-test-cmd
sets the test commandprojectile-project-run-cmd
sets the run commandprojectile-project-compilation-dir
sets the directory to run compilation commands in.
These will override whatever type Projectile has assigned.
Example: .dir-locals.el
for a Common Lisp project
((nil . ((projectile-project-test-cmd . "sbcl --script test.lisp"))))
The .dir-locals.el
overrides make it possible to customize projects no matter
what language or setup they're using.
Switching between tests and source files
Projectile's C-c p t command works most of the time, but a couple of my projects needed to be tweaked slightly to work properly due to the way test files are named and found.
To find the appropriate test file, Projectile strips the current filename of its path and extension, and then checks for a specific prefix or suffix.
For example:
"project/src/module/my_file.rb
" will be stripped down to just
"my_file
". Ruby projects use "_test
" as the suffix, meaning Projectile will
attempt to open "my_file_test.rb
" wherever it is located.
Some of my projects use the same name for source and test files, but stores them in different directories. It may be possible to extend this behaviour, but I'm still looking into that.
Switching between controllers and views
projectile-rails can be used to switch between models and views within rails projects.
For none-Rails projects, there are a couple of options, although neither are perfect:
- C-c p a – Switches between files with the same name but a different extension.
- C-c p g – Jumps to the file at the current point. This worked well for projects that explicitly named view templates.
Running grep and occur
Both of these options are supported and very quick:
- C-c p s g – Runs grep on the entire project
- C-c p o – Runs
occur
on all open project buffers
Running git
C-c p v opens version control for the current project. It
automatically works out the best option based on what version control the
project is under. For example, projects under git will open magit
if installed.
Renaming files
There's no shortcut for renaming files, but being able to quickly open dired
for project directories makes the whole process much easier.
Opening a terminal
C-c p ! runs a shell command in the project root. There's no shortcut to open a terminal .
More information
There's a full list of commands available on the Projectile project page: http://batsov.com/projectile/#interactive-commands
This post is part of the "Exploring my Emacs packages" series.