Projectile

Overview

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).

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.

Features

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.

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.

Projectile in Action

Here’s a glimpse of Projectile in action (using ivy for minibuffer completion):

Projectile Screenshot

In this short demo you can see:

  • finding files in a project

  • switching between implementation and test

  • switching between projects

You can see in the modeline the keybindings that are used in the demo and the commands that they invoked.[2]

Supporting Projectile

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.

A bit of trivia for you - Projectile was my very first open-source project and it has a very special place in my heart!

What’s Next?

So, what to do next? While you can peruse the documentation in whatever way you’d like, here are a few recommendations:

1. That file is called a "project marker" in Projectile’s lingo.
2. Courtesy of keycast-mode.