1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
|
= 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.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)
* 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 package) 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
|
