= Projectile versus project.el

NOTE: As both projects are moving targets this page might not reflect the differences between them accurately.

Projectile was created at a time when Emacs didn't feature built-in project
navigation functionality. Eventually this changed in Emacs 25 with the introduction of `project.el` and a lot of people have been asking what are the advantages of using
Projectile over the built-in library. This section of the documentation will try to answer this question.

When `project.el` was originally introduced it's feature-set was quite spartan, but it has added some new features in every Emacs release and circa 2024 it should cover the needs of most casual users. I'm guessing that Projectile inspired many features in `project.el`, and Projectile itself was inspired by tools like IntelliJ IDEA.

== TLDR;

If the functionality in `project.el` is good enough for you than you should probably use `project.el`.

== At a glance

NOTE: As of early 2024. (Projectile 2.8 and `project.el` in Emacs 29)

|===
| | Projectile | project.el

| Created in
| 2011
| 2014 footnote:[It was introduced in Emacs 25.1.]

| Supported Emacs versions
| 26+
| 26+ footnote:[Note that the versions bundled with older Emacsen will miss some of its modern features. `project.el` is distributed as a package as well, so you can still get some of the newer functionality on older Emacsen.]

| Built-in
| no
| yes

| Package Availability
| MELPA, MELPA Stable, NonGNU ELPA
| GNU ELPA

| Indexing Strategies
| 3 (`native`, `hybrid`, `alien`)
| 1 (similar to Projectile's alien strategy)

| Native Project Config
| Yes (`.projectile`)
| No

| Project Cache
| Yes
| No

| Built-in Project Types
| 60+
| n/a

| Number of Configuration Options
| ~90
| ~20

| Number of Commands
| 80+
| 30+

| Minor Mode
| Yes
| No

| Global Keybindings
| Require user setup
| Out-of-the-box (`C-x p`)

| Integration with `xref`
| Yes
| Yes

| Feature-set
| Extensive
| Essential

| Extensions
| ~20
| ~10

| Contribution Process
| Light-weight
| Somewhat complicated (standard for Emacs)
|===

== Notable Differences

=== Minor Mode vs Global Keymap

Projectile makes heavy use of `projectile-mode`, which provides some additional features (e.g. project status in the modeline).
You can use Projectile without it, but I guess few people do so. Most of Projectile's functionality will work fine even if the mode is not active.

`project.el` on the other hand, just adds its own keymap under the global keymap (using the prefix `C-x p`). You can do the same for Projectile,
of course, if you want to.

=== Project Indexing Strategies

Projectile has multiple project indexing strategies to cover a wide variety of use cases. `project.el` has only one, which is more or less the same
as Projectile's `alien` strategy. Admittedly, that's probably the most commonly used strategy.

=== `.projectile`

Projectile has it's own project marker/configuration file. It's a remnant of the early days of the project where a wanted to build a tool that didn't
rely on the third-party applications and it's significance today is not that big. (it will be completely ignored unless you're using `native` or `hybrid` indexing)

== Projectile's Pros

* Projectile targets Emacs 26, so you can get all the features even with older Emacs releases
* Projectile has different project indexing strategies, which offer you a lot of flexibility in different situations
* Projectile supports a lot of project types out-of-the-box (e.g. `ruby`, `Rails`, `cabal` and `dune`)
* Projectile has a lot more features, although one can argue that some of them are rarely needed
  ** Projectile's Commander is pretty cool for project switching!
* It's easier to contribute to Projectile
  ** Projectile is hosted in GitHub
  ** It accepts pull requests
  ** You don't need to sign a contributor agreement
* Projectile has more extensive documentation
  ** You can compare it with [project.el's documentation](https://www.gnu.org/software/emacs/manual/html_node/emacs/Projects.html) and decide for themselves

== Projectile's Cons

* Third-party dependency, developed outside of Emacs. This is both a pro and con depending on one's perspective, but I know that many people prefer built-in packages, so I've put it under "cons".
  ** Built-in packages in theory should be maintained better (or at least for longer), as they have the Emacs team behind them.
  ** While Projectile has a rich ecosystem of extensions, over a long enough period of time likely `project.el` will take the lead.
* Due to its larger size, one can argue that Projectile is more complex than `project.el`
  ** Admittedly I would have done some things differently if were starting Projectile today, but I don't think Projetile's core complexity is high.
