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

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.

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

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, ranked by frecency

- 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

- find a file of a given kind and jump between related files (e.g. a Rails model and its controller)

- 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

- per-project sessions with tab-bar workspaces (restore each project’s layout and buffers, even across restarts)

- kill (close) all project buffers

- replace in project, with a reviewable before/after preview

- multi-occur in project buffers

- grep (search) in project (multiple back-ends like `ag`, `rg`, and a native reviewable results UI)

- find references in project (using `xref` internally)

- visit project in `dired`

- run project commands and tasks (build/test/run, your own named tasks, and the npm scripts, Make targets and justfile recipes a project already defines)

- work on one part of a monorepo - find files in a subproject, build or test just the module you’re in

- run the test at point (tree-sitter, Emacs 29+)

- works with any `completing-read`-based minibuffer completion UI (Vertico, Consult, `fido-mode`, etc.)

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

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]

## 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 packages) via one of the following platforms:

- GitHub Sponsors

- ko-fi

- PayPal

- Patreon

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!

## 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:

- 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

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