= Projectile

== Overview

*Projectile* is a **project** **i**nteraction **l**ibrary for **E**macs. 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.footnote:[That file is called a "project marker" in Projectile's lingo.] 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 xref:projects.adoc[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 https://github.com/leoliu/ggtags[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 xref:extensions[Projectile extensions] that add even more features.

== Projectile in Action

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

image::projectile-demo.gif[Projectile Screenshot]

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.footnote:[Courtesy of
https://metaredux.com/posts/2019/12/07/dead-simple-emacs-screencasts.html[keycast-mode].]

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

* https://github.com/sponsors/bbatsov[GitHub Sponsors]
* https://ko-fi.com/bbatsov[ko-fi]
* https://www.paypal.me/bbatsov[PayPal]
* https://www.patreon.com/bbatsov[Patreon]

Check out the xref:contributing.adoc["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:

* xref:installation.adoc[Install] Projectile and get it xref:usage.adoc[up and running]
* Get familiar with xref:projects.adoc[Projectile's notion of projects]
* xref:configuration.adoc[Configure] Projectile to your liking
* Explore the xref:extensions.adoc[Projectile extensions] that can make you more productive