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).
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.
This library provides easy project management and navigation. The concept of a
project is pretty basic - just a folder containing some special file (e.g. a VCS
marker or a project descriptor file like pom.xml
or Gemfile
). Projectile
will auto-detect pretty much every popular project type out of the box
and you can easily extend it with additional project types.
Here are some of Projectile's features:
- jump to a file in project
- 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
- grep (search) in project
- replace in project
- find references in project (using
xref
internally) - run shell commands in a project (e.g.
make
,lein
) - 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.
I've been developing Projectile for over a decade now (since 2011). While it's a fun project to work on, it still requires a lot of time and energy to maintain.
You can support my work on Projectile via PayPal, Patreon and GitHub Sponsors.
Here's a glimpse of Projectile in action (using ivy
):
In this short demo you can see:
- finding files in a project
- switching between implementation and test
- switching between projects
The instructions that follow are meant to get you from zero to a running Projectile setup in a minute. Visit the online documentation for (way) more details.
package.el
is the built-in package manager in Emacs.
Projectile is available on all major package.el
community
maintained repos - NonGNU ELPA,
MELPA Stable
and MELPA.
You can install Projectile with the following command:
M-x package-install
[RET] projectile
[RET]
Alternatively, users of Debian 9 or later or Ubuntu 16.04 or later may
simply apt-get install elpa-projectile
.
Finally add this to your Emacs config:
(projectile-mode +1)
;; Recommended keymap prefix on macOS
(define-key projectile-mode-map (kbd "s-p") 'projectile-command-map)
;; Recommended keymap prefix on Windows/Linux
(define-key projectile-mode-map (kbd "C-c p") 'projectile-command-map)
Those keymap prefixes are just a suggestion. Feel free to put there whatever works best for you.
Enable projectile-mode
, open a file in one of your projects and type a command such as C-c p f.
See the online documentation for more details.
To get the most of Projectile you also need to enable (and potentially install) some minibuffer completion framework (e.g. ido
, ivy
or selectrum
). See this section of the documentation for more details.
Note: Historically projectile-completion-system
defaulted to ido
, but this was changed in version 2.3. You may need to enable ido-mode
in your Emacs configuration if updating from an older version of Projectile.
- Some operations like search (grep) depend (presently) on external
utilities such as
find
orfd
(version 8.3.0+).- for older
fd
version add(setq projectile-generic-command "fd . -0 --type f --color=never")
to your init-file
- for older
- Commands depending on external utilities might misbehave on the
fish
shell. - Using Projectile over TRAMP might be slow in certain cases.
- Some commands might misbehave on complex project setups (e.g. a git project with submodules).
- Projectile was mostly tested on Unix OS-es (e.g. GNU/Linux and macOS), so some functionality might not work well on Windows.
- In Git repositories, deleted files are still shown in
projectile-find-file
until their deletions are staged, due to a limitation ofgit ls-files
. If you install fd then it is automatically used instead, and does not have this problem. (You can inhibit the use offd
by settingprojectile-git-use-fd
to nil.)
Check out the project's issue list a list of unresolved issues. By the way - feel free to fix any of them and send me a pull request. :-)
Here's a list of all the people who have contributed to the development of Projectile (a.k.a. Projectile's Hall of Fame).
Joining this esteemed group of people is only a commit away!
A fairly extensive changelog is available here.
Copyright © 2011-2024 Bozhidar Batsov and contributors.
Distributed under the GNU General Public License, version 3