= 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, xref:indexing.adoc#file-ranking-frecency[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
* xref:projects.adoc#finding-files-by-kind[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
* xref:sessions.adoc[per-project sessions] with tab-bar workspaces (restore each project's layout and buffers, even across restarts)
* kill (close) all project buffers
* xref:usage.adoc#reviewing-and-applying-replacements[replace in project], with a reviewable before/after preview
* multi-occur in project buffers
* xref:usage.adoc#reviewing-search-matches[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 xref:tasks.adoc#project-tasks[project commands and tasks] (build/test/run, your own named tasks, and the npm scripts, Make targets and justfile recipes a project already defines)
* xref:tasks.adoc#subprojects[work on one part of a monorepo] - find files in a subproject, build or test just the module you're in
* xref:tasks.adoc#running-the-test-at-point[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 xref:extensions.adoc[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
