Projectile is a project interaction library for Emacs. Its goal is to
provide a nice set of features operating on a project level without
introducing external dependencies (when feasible). For instance -
finding project files has a portable implementation written in pure
Emacs Lisp without the use of GNU find
(but for performance sake an
indexing mechanism backed by external commands exists as well).
Tip
|
In practical terms the fact that Projectile can index the files in
a project without shelling out to find , git or whatever, means
that unlike many similar tools it will work on Windows without any
additional setup.
|
Projectile tries to be practical - portability is great, but if some external tools could speed up some task substantially and the tools are available, Projectile will leverage them.
Projectile provides easy project management and navigation. The
concept of a project is pretty basic - just a folder containing
special file.[1] Currently most VCS repos (e.g. git
, mercurial
, etc)
are considered projects by default, as are directories containing
build tools (e.g. maven
, leiningen
, etc) or framework markers
(e.g. Ruby on Rails). If you want to mark a folder manually as a
project just create an empty .projectile
file in it.
Tip
|
You can learn more about Projectile’s notion of a project here. |
Here are some of Projectile’s features in no particular order:
-
jump to a file in project
-
jump to files at point in project
-
jump to a directory in project
-
jump to a file in a directory
-
jump to a project buffer
-
jump to a test in project
-
toggle between files with same names but different extensions (e.g.
.h
←→.c/.cpp
,Gemfile
←→Gemfile.lock
) -
toggle between code and its test (e.g.
main.service.js
←→main.service.spec.js
) -
jump to recently visited files in the project
-
switch between projects you have worked on
-
kill (close) all project buffers
-
replace in project
-
multi-occur in project buffers
-
grep (search) in project (this supports multiple back-ends like
ag
,rg
, etc) -
find references in project (using
xref
internally) -
regenerate project etags or gtags (requires ggtags).
-
visit project in
dired
-
run
make
in a project with a single key chord -
browse dirty version controlled projects
-
support for multiple minibuffer completion/selection libraries (
ido
,ivy
,helm
and the default completion system) -
automatic project discovery (see
projectile-project-search-path
) -
integration with the built-in
project.el
library
There’s also a rich ecosystem of third-party Projectile extensions that add even more features.
Here’s a glimpse of Projectile in action (using ivy
for minibuffer completion):
In this short demo you can see:
-
finding files in a project
-
switching between implementation and test
-
switching between projects
Tip
|
You can see in the modeline the keybindings that are used in the demo and the commands that they invoked.[2] |
I’ve started working on Projectile in 2011 and I’ve been maintaining it ever since. It slowly grew from an obscure project with a single user to one of the most popular packages in the realm of Emacs. It’s a fun project, but it also requires a lot of work.
You can support my work on Projectile (and all my other Emacs package) via one of the following platforms:
Check out the "Contributing" section of the docs for all the ways in which you can help Projectile.
Note
|
A bit of trivia for you - Projectile was my very first open-source project and it has a very special place in my heart! |
So, what to do next? While you can peruse the documentation in whatever way you’d like, here are a few recommendations:
-
Install Projectile and get it up and running
-
Get familiar with Projectile’s notion of projects
-
Configure Projectile to your liking
-
Explore the Projectile extensions that can make you more productive