Projectile

Synopsis

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). Currently git, mercurial, darcs and bazaar repos are considered projects by default. So are lein, maven, sbt, scons, rebar3 and bundler projects. If you want to mark a folder manually as a project just create an empty .projectile file in it.

Here are some of Projectile's features:

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 in project
regenerate project etags or gtags (requires ggtags).
visit project in dired
run make in a project with a single key chord
check for dirty repositories
toggle read-only mode for the entire project
support for multiple minibuffer completion/selection libraries (ido, ivy, helm and the default completion system)

Projectile in Action

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

You can support my work on Projectile via PayPal, Patreon and GitHub Sponsors.

Quickstart

The instructions that follow are meant to get you from zero to a running Projectile setup in a minute. Visit the user manual for (way) more details.

Installation

package.el is the built-in package manager in Emacs.

Projectile is available on the two major package.el community maintained repos - 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)
(define-key projectile-mode-map (kbd "s-p") 'projectile-command-map)
(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.

Basic Usage

Enable projectile-mode, open a file in one of your projects and type a command such as C-c p f.

See the user manual for more details.

Caveats

Some operations like search (grep) depend (presently) on external utilities such as find.
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

Known issues

Check out the project's issue list a list of unresolved issues. By the way - feel free to fix any of them and sent me a pull request. :-)

Contributors

Here's a list of all the people who have contributed to the development of Projectile.

Changelog

A fairly extensive changelog is available here.

License

Distributed under the GNU General Public License, version 3

dmusican/projectile