From bf8bc81868273bd1ec75c57f49513d228373a71e Mon Sep 17 00:00:00 2001 From: Bozhidar Batsov Date: Sat, 21 Jul 2018 11:48:19 +0300 Subject: [PATCH] Tweak the docs a bit --- doc/configuration.md | 75 ++++++++++++++++++++++++++------------------ doc/faq.md | 21 +++++++++++++ doc/index.md | 29 ++++++++++++----- doc/installation.md | 4 ++- doc/usage.md | 11 +++---- mkdocs.yml | 1 + 6 files changed, 95 insertions(+), 46 deletions(-) create mode 100644 doc/faq.md diff --git a/doc/configuration.md b/doc/configuration.md index 495a1b6d9..de6940249 100644 --- a/doc/configuration.md +++ b/doc/configuration.md @@ -1,7 +1,13 @@ -#### Indexing method +In the typical style of Emacs, Projectile is **extremely** configurable. +Pretty much every aspect of its behaviour can be tweaked or extended. + +In this section we'll go over some of the most common things you might +want to fine-tune to make Projectile fit your workflow better. + +## Project indexing method Projectile has two modes of operation - one is portable and is -implemented in Emacs Lisp(therefore it's native to Emacs and is known +implemented in Emacs Lisp (therefore it's *native* to Emacs and is known as the `native indexing method`) and the other relies on external commands like `find`, `git`, etc to obtain the list of files in a project. @@ -20,13 +26,14 @@ To force the use of external indexing in Windows: (setq projectile-indexing-method 'alien) ``` -This can speed up Projectile in Windows significantly. The disadvantage of this -method is that it's not well supported on Windows systems. If there's problem, -you can always use native indexing mode. +This can speed up Projectile in Windows significantly. The +disadvantage of this method is that it's not well supported on Windows +systems, as it requires setting up some Unix utilities there. If +there's problem, you can always use native indexing mode. -#### Caching +## Caching -##### Project files +### Project files Since indexing a big project is not exactly quick (especially in Emacs Lisp), Projectile supports caching of the project's files. The caching @@ -52,7 +59,7 @@ The project cache is persistent and will be preserved during Emacs restarts. You can purge an individual file from the cache with `M-x projectile-purge-file-from-cache` or an entire directory with `M-x projectile-purge-dir-from-cache`. -##### File exists cache +### File exists cache Projectile does many file existence checks since that is how it identifies a project root. Normally this is fine, however in some situations the file system @@ -82,7 +89,7 @@ needed but possible: (setq projectile-file-exists-local-cache-expire (* 5 60)) ``` -#### Using Projectile everywhere +## Using Projectile everywhere If you want Projectile to be usable in every directory (even without the presence of project file): @@ -92,7 +99,7 @@ If you want Projectile to be usable in every directory (even without the presenc This might not be a great idea if you start Projectile in your home folder for instance. :-) -#### Switching projects +## Switching projects When running `projectile-switch-project` (C-c p p) Projectile invokes the command specified in `projectile-switch-project-action` (by default it is @@ -101,7 +108,7 @@ the command specified in `projectile-switch-project-action` (by default it is Depending on your personal workflow and habits, you may prefer to alter the value of `projectile-switch-project-action`: -###### `projectile-find-file` +### `projectile-find-file` This is the default. With this setting, once you have selected your project via Projectile's completion system (see below), you will @@ -110,13 +117,13 @@ is capable of retrieving files in all sub-projects under the project root, such as Git submodules. Currently, only Git is supported. Support for other VCS will be added in the future. -###### `projectile-find-file-in-known-projects` +### `projectile-find-file-in-known-projects` Similar to `projectile-find-file` but lists all files in all known projects. Since the total number of files could be huge, it is beneficial to enable caching for subsequent usages. -###### `projectile-find-file-dwim` +### `projectile-find-file-dwim` If point is on a filepath, Projectile first tries to search for that file in project: @@ -140,7 +147,7 @@ files with character 'a' in that directory is presented. - If it finds nothing, display a list of all files in project for selecting. -###### `projectile-dired` +### `projectile-dired` ```el (setq projectile-switch-project-action #'projectile-dired) @@ -150,7 +157,7 @@ With this setting, once you have selected your project, the top-level directory of the project is immediately opened for you in a dired buffer. -###### `projectile-find-dir` +### `projectile-find-dir` ```el (setq projectile-switch-project-action #'projectile-find-dir) @@ -169,9 +176,9 @@ want to set in order to allow for the occasions where you want to select the top-level directory. -#### Completion Options +## Completion Options -##### Ido +### Ido By default Projectile uses `ido` as its completion system. `ido` is extremely popular and it is built into Emacs. @@ -181,7 +188,7 @@ As already noted above if you're going to use the `ido` completion it's [flx-ido package](https://github.com/lewang/flx), which provides a much more powerful alternative to `ido`'s built-in `flex` matching. -##### Ivy (recommended) +### Ivy (recommended) Another completion option is [ivy](https://github.com/abo-abo/swiper): @@ -189,7 +196,7 @@ Another completion option is [ivy](https://github.com/abo-abo/swiper): (setq projectile-completion-system 'ivy) ``` -##### Basic (Emacs's default) +### Basic (Emacs's default) If you don't like `ido` and `ivy` you can use regular completion: @@ -199,7 +206,7 @@ If you don't like `ido` and `ivy` you can use regular completion: You might want to combine default completion with `icomplete-mode` for optimum results. -##### Custom Completion Function +### Custom Completion Function You can also set `projectile-completion-system` to a function: @@ -217,16 +224,18 @@ the file name (not including path) and if the file selected is not unique, another completion with names relative to project root appears. -##### Regenerate tags +## Regenerate tags To be able to regenerate a project's tags via `projectile-tags-command`, you should install and add to the PATH [Exuberant Ctags](http://ctags.sourceforge.net/) instead of a plain ctags, which ships with Emacs distribution. -### Adding Custom Project Types +## Adding Custom Project Types -If a project you are working on is recognized incorrectly or you want to add your own type of projects you can add following to your Emacs initialization code +If a project you are working on is recognized incorrectly or you want +to add your own type of projects you can add following to your Emacs +initialization code ```el (projectile-register-project-type 'npm '("package.json") @@ -235,6 +244,7 @@ If a project you are working on is recognized incorrectly or you want to add you :run "npm start" :test-suffix ".spec") ``` + What this does is: 1. add your own type of project, in this case `npm` package. 2. add a file in a root of the project that helps to identify the type, in this case it is `package.json`. @@ -257,7 +267,7 @@ Option | Documentation :test-prefix | A prefix to generate test files names. :test-suffix | A suffix to generate test files names. -### Customizing project root files +## Customizing project root files You can set the values of `projectile-project-root-files`, `projectile-project-root-files-top-down-recurring`, @@ -271,7 +281,7 @@ To customize project root files settings: M-x customize-group RET projectile RET ``` -#### File-local project root definitions +### File-local project root definitions If you want to override the projectile project root for a specific file, you can set the file-local variable `projectile-project-root`. This @@ -279,7 +289,7 @@ can be useful if you have files within one project that are related to a different project (for instance, Org files in one git repo that correspond to other projects). -### Storing project settings +## Storing project settings From project to project, some things may differ even in the same language - coding styles, auto-completion sources, etc. If you need @@ -311,7 +321,7 @@ You can also quickly visit or create the `dir-locals-file` with Here are a few examples of how to use this feature with Projectile. -#### Configuring Projectile's Behavior +## Configuring Projectile's Behavior Projectile exposes many variables (via `defcustom`) which allow users to customize its behavior. Directory variables can be used to set @@ -344,7 +354,7 @@ your project, you could customize it with the following: ((nil . ((projectile-project-name . "your-project-name-here")))) ``` -#### Configure a Project's Compilation, Test and Run commands +## Configure a Project's Compilation, Test and Run commands There are a few variables that are intended to be customized via `.dir-locals.el`. @@ -361,7 +371,7 @@ external command or an Emacs Lisp function: (setq projectile-test-cmd #'custom-test-function) ``` -### Idle Timer +## Idle Timer Projectile can be configured to run the hook `projectile-idle-timer-hook` every time Emacs is in a project and has @@ -380,7 +390,7 @@ additional functions to the hook using `add-hook`: (add-hook 'projectile-idle-timer-hook #'my-projectile-idle-timer-function) ``` -### Mode line indicator +## Mode line indicator By default the minor mode indicator of Projectile appears in the form " Projectile[ProjectName]". This is configurable via the custom variable @@ -390,3 +400,8 @@ By default the minor mode indicator of Projectile appears in the form The project name will not appear by default when editing remote files (via TRAMP), as recalculating the project name (this is done on every keystroke) is a fairly slow operation there. + +!!! Warning + + Be extremely careful about what you put here, as all the code in the lighter + gets evaluated on every keystroke! diff --git a/doc/faq.md b/doc/faq.md new file mode 100644 index 000000000..1fd135eef --- /dev/null +++ b/doc/faq.md @@ -0,0 +1,21 @@ +## Why did you name it Projectile? + +I wanted a name that's not as boring as `project.el` and implies that your +interaction with projects is going to speed up significantly. :-) + +## Does Projectile work with TRAMP? + +Yeah, it does. I don't use TRAMP myself, however, so I never paid that +much attention to the TRAMP support. It's mostly community-maintained. + +## Why does Projectile violate the rule not to bind keys in the user keymap? + +I opted for the `C-c p` prefix fully aware that this violates a very +established Emacs convention, mostly because it felt practical and +because pressing `C-c C-p` is not super convenient for many +people. I've come to regret this decision, though, and it will likely +be reverted down the road. + +## Do you need some help cleanup up all those tickets that have piled up? + +Certainly! diff --git a/doc/index.md b/doc/index.md index 06929d669..4840e4b24 100644 --- a/doc/index.md +++ b/doc/index.md @@ -5,17 +5,29 @@ 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. -This library provides easy project management and navigation. The +Here's a glimpse of Projectile in action (find file in project using `ido`): + +![Projectile Screenshot](screenshots/projectile.png) + +Projectile provides easy project management and navigation. The concept of a project is pretty basic - just a folder containing -special file. Currently `git`, `mercurial`, `darcs` and `bazaar` repos -are considered projects by default. So are `lein`, `maven`, `sbt`, -`scons`, `rebar` and `bundler` projects. If you want to mark a folder -manually as a project just create an empty `.projectile` file in -it. Some of Projectile's features: +special file. 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. Some of +Projectile's features: * jump to a file in project * jump to files at point in project @@ -36,9 +48,10 @@ it. Some of Projectile's features: * run make in a project with a single key chord * browse dirty version controlled projects -Here's a glimpse of Projectile in action: +!!! Info -![Projectile Screenshot](screenshots/projectile.png) + A bit of trivia for you - Projectile was my very first open-source project and + it has a very special place in my heart! You can support my work on Projectile via [PayPal](https://www.paypal.me/bbatsov), diff --git a/doc/installation.md b/doc/installation.md index d486c4503..48f5b9479 100644 --- a/doc/installation.md +++ b/doc/installation.md @@ -5,7 +5,9 @@ release). If you're new to Emacs you might want to go through [the guided tour of Emacs](https://www.gnu.org/software/emacs/tour/index.html) and the built-in tutorial (just press C-h t). -Projectile officially supports Emacs 25.1+. +!!! Note + + Projectile officially supports Emacs 25.1+. ## Installation diff --git a/doc/usage.md b/doc/usage.md index 9e1493231..45da8057a 100644 --- a/doc/usage.md +++ b/doc/usage.md @@ -1,6 +1,4 @@ -## Usage - -### Basic setup +## Basic setup !!! Note @@ -23,7 +21,7 @@ If you're going to use the default `ido` completion it's [flx-ido package](https://github.com/lewang/flx), which provides a much more powerful alternative to `ido`'s built-in `flex` matching. -### Interactive Commands +## Interactive Commands Here's a list of the interactive Emacs Lisp functions, provided by Projectile: @@ -98,8 +96,7 @@ commands. Here's an example that adds `super-p` as the extra prefix: ``` You can also bind the `projectile-command-map` to any other map you'd -like (including the global keymap). Prelude does this for its -[prelude-mode-map](https://github.com/bbatsov/prelude/blob/master/core/prelude-mode.el#L71). +like (including the global keymap). For some common commands you might want to take a little shortcut and leverage the fairly unused `Super` key (by default `Command` on Mac @@ -116,7 +113,7 @@ add to your Emacs config: Note that the `Super` keybindings are not usable in Windows. Emacs Prelude already adds those extra keybindings. -### Ignoring files +## Ignoring files If you'd like to instruct Projectile to ignore certain files in a project, when indexing it you can do so in the `.projectile` file by diff --git a/mkdocs.yml b/mkdocs.yml index 634a4051a..6ec52cbfa 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -9,6 +9,7 @@ pages: - Usage: usage.md - Configuration: configuration.md - Extensions: extensions.md +- FAQ: faq.md - Contributing: contributing.md - Support: support.md extra_css: