diff --git a/legacy-docs/blank.md b/legacy-docs/blank.md new file mode 100644 index 000000000..564dd878b --- /dev/null +++ b/legacy-docs/blank.md @@ -0,0 +1 @@ +This page will be removed once we can drop all legacy pages. diff --git a/legacy-docs/configuration.md b/legacy-docs/configuration.md deleted file mode 100644 index ccb28aa0d..000000000 --- a/legacy-docs/configuration.md +++ /dev/null @@ -1,376 +0,0 @@ -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 three modes of operation - one is portable and is -implemented in Emacs Lisp (therefore it's *native* to Emacs and is -known as the `native indexing method`) and the other two (`hybrid` and -`alien`) rely on external commands like `find`, `git`, etc to -obtain the list of files in a project. - -The `alien` indexing method optimizes to the limit the speed of -the `hybrid` indexing method. This means that Projectile will not do -any processing or sorting of the files returned by the external commands -and you're going to get the maximum performance possible. This behaviour -makes a lot of sense for most people, as they'd typically be putting -ignores in their VCS config (e.g. `.gitignore`) and won't care about -any additional ignores/unignores/sorting that Projectile might also -provide. - -!!! Info - - By default the `alien` method is used on all operating systems except Windows. - Prior to Projectile 2.0 `hybrid` used to be the default (but to make things - confusing `hybrid` used to be known as `alien` back then). - -To force the -use of native indexing in all operating systems: - -```elisp -(setq projectile-indexing-method 'native) -``` - -To force the use of hybrid indexing in all operating systems: - -```elisp -(setq projectile-indexing-method 'hybrid) -``` - -To force the use of alien indexing in all operating systems: - -```elisp -(setq projectile-indexing-method 'alien) -``` - -This can speed up Projectile in Windows significantly (especially on -big projects). 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. - -### Alien indexing - -The alien indexing works in a pretty simple manner - it simply shells -out to a command that returns the list of files within a project. -For version-controlled projects by default Projectile will use the -VCS itself to obtain the list of files. As an example, here is the -command that Projectile uses for Git projects: - -``` -git ls-files -zco --exclude-standard -``` - -For every supported VCS there's a matching Projectile defcustom holding the command -to invoke for it (e.g. `projectile-git-command`, `projectile-hg-command`, etc). - -!!! Warning - - If you ever decide to tweak those keep in mind that the command should always be returning - the list of files **relative** to the project root and the resulting file list should be 0-delimited - (as opposed to newline delimited). - -For non-VCS projects Projectile will invoke whatever is in `projectile-generic-command`. By default that's: - -``` -find . -type f -print0 -``` - -!!! Tip - - It's a great idea to install [fd](https://github.com/sharkdp/fd) which is much faster than `find`. - If `fd` is found, projectile will use as a replacement for `find`. - -## Sorting - -You can choose how Projectile sorts files by customizing `projectile-sort-order`. - -!!! Info - - Note that if Alien indexing is set, files are not sorted by Projectile at all. - -The default is to not sort files: - -```elisp -(setq projectile-sort-order 'default) -``` - -To sort files by recently opened: - -```elisp -(setq projectile-sort-order 'recentf) -``` - -To sort files by recently active buffers and then recently opened files: - -```elisp -(setq projectile-sort-order 'recently-active) -``` - - - -To sort files by modification time (mtime): - -```elisp -(setq projectile-sort-order 'modification-time) -``` - -To sort files by access time (atime): - -```elisp -(setq projectile-sort-order 'access-time) -``` - - -## Caching - -### 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 -is enabled by default whenever native indexing is enabled. - -To enable caching unconditionally use this snippet of code: - -```elisp -(setq projectile-enable-caching t) -``` - -At this point you can try out a Projectile command such as s-p f (M-x projectile-find-file RET). - -Running C-u s-p f will invalidate the cache prior to -prompting you for a file to jump to. - -Pressing s-p z will add the currently visited file to the -cache for current project. Generally files created outside Emacs will -be added to the cache automatically the first time you open them. - -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 - -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 -speed is much slower than usual and can make emacs "freeze" for extended -periods of time when opening files and browsing directories. - -The most common example would be interfacing with remote systems using -TRAMP/ssh. By default all remote file existence checks are cached - -To disable remote file exists cache that use this snippet of code: - -```elisp -(setq projectile-file-exists-remote-cache-expire nil) -``` - -To change the remote file exists cache expire to 10 minutes use this snippet -of code: - -```elisp -(setq projectile-file-exists-remote-cache-expire (* 10 60)) -``` - -You can also enable the cache for local file systems, that is normally not -needed but possible: - -```elisp -(setq projectile-file-exists-local-cache-expire (* 5 60)) -``` - -## Using Projectile everywhere - -If you want Projectile to be usable in every directory (even without the presence of project file): - -```elisp -(setq projectile-require-project-root nil) -``` - -!!! Tip - - This might not be a great idea if you start Projectile in your home folder for instance. :-) - -## Switching projects - -By default, projectile does not include the current project in the list when -switching projects. If you want to include the current project, customize -variable `projectile-current-project-on-switch`. - -When running `projectile-switch-project` (s-p p) Projectile invokes -the command specified in `projectile-switch-project-action` (by default it is -`projectile-find-file`). - -!!! Tip - - Invoking the command with a prefix argument (C-u s-p p) will trigger - the Projectile Commander, which gives you quick access to most common commands - you might want to invoke on a project. - -Depending on your personal workflow and habits, you -may prefer to alter the value of `projectile-switch-project-action`: - -### `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 -remain in the completion system to select a file to visit. `projectile-find-file` -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` - -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` - -If point is on a filepath, Projectile first tries to search for that -file in project: - -- If it finds just a file, it switches to that file instantly. This -works even if the filename is incomplete, but there's only a single file -in the current project that matches the filename at point. For example, -if there's only a single file named "projectile/projectile.el" but the -current filename is "projectile/proj" (incomplete), projectile-find-file -still switches to "projectile/projectile.el" immediately because this -is the only filename that matches. - -- If it finds a list of files, the list is displayed for selecting. A -list of files is displayed when a filename appears more than one in the -project or the filename at point is a prefix of more than two files in a -project. For example, if `projectile-find-file' is executed on a -filepath like "projectile/", it lists the content of that directory. -If it is executed on a partial filename like "projectile/a", a list of -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` - -```elisp -(setq projectile-switch-project-action #'projectile-dired) -``` - -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` - -```elisp -(setq projectile-switch-project-action #'projectile-find-dir) -``` - -With this setting, once you have selected your project, you will -remain in Projectile's completion system to select a sub-directory of -your project, and then *that* sub-directory is opened for you in a -dired buffer. If you use this setting, then you will probably also -want to set - -```elisp -(setq projectile-find-dir-includes-top-level t) -``` - -in order to allow for the occasions where you want to select the -top-level directory. - -## Completion Options - -### Ido - -By default Projectile uses `ido` as its completion system. `ido` is -extremely popular and it is built into Emacs. - - -!!! Tip - - As already noted above if you're going to use the `ido` completion it's - **extremely highly** recommended that you install the optional - [flx-ido package](https://github.com/lewang/flx), which provides a much - more powerful alternative to `ido`'s built-in `flex` matching. - -### Ivy (recommended) - -Another completion option is [ivy](https://github.com/abo-abo/swiper): - -```elisp -(setq projectile-completion-system 'ivy) -``` - -### Basic (Emacs's default) - -If you don't like `ido` and `ivy` you can use regular completion: - -```elisp -(setq projectile-completion-system 'default) -``` - -You might want to combine default completion with `icomplete-mode` for optimum results. - -### Custom Completion Function - -You can also set `projectile-completion-system` to a function: - -```elisp -(setq projectile-completion-system #'my-custom-completion-fn) -(setq projectile-completion-system - (lambda (prompt choices) - ;; ... - )) -``` - -An example of a custom completion function is -[this one](https://gist.github.com/rejeep/5933343), which only show -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 - -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. - -## Idle Timer - -Projectile can be configured to run the hook -`projectile-idle-timer-hook` every time Emacs is in a project and has -been idle for `projectile-idle-timer-seconds` seconds (default is 30 -seconds). To enable this feature, run: - -``` -M-x customize-group RET projectile RET -``` - -and set `projectile-enable-idle-timer` to non-nil. By default, -`projectile-idle-timer-hook` runs `projectile-regenerate-tags`. Add -additional functions to the hook using `add-hook`: - -```elisp -(add-hook 'projectile-idle-timer-hook #'my-projectile-idle-timer-function) -``` - -## Mode line indicator - -By default the minor mode indicator of Projectile appears in the form -" Projectile[ProjectName:ProjectType]". This is configurable via several custom variables: - -* `projectile-mode-line-prefix` (by default " Projectile") controls the static part of the mode-line -* `projectile-dynamic-mode-line` (by default `t`) controls whether to display the project name & type part of the mode-line -* `projectile-mode-line-function` (by default `projectile-default-mode-line`) controls the actual function to be invoked to generate the mode-line. If you'd like to show different info you should supply a custom function to replace the default, for example `(setq projectile-mode-line-function '(lambda () (format " Proj[%s]" (projectile-project-name))))` - -!!! Note - - The project name & type will not appear when editing remote files - (via TRAMP), as recalculating the project name is a fairly slow operation there - and would slow down a bit opening the files. They will also not appear for - non-file buffers, as they get updated via `find-file-hook`. diff --git a/legacy-docs/contributing.md b/legacy-docs/contributing.md deleted file mode 100644 index b92f5873b..000000000 --- a/legacy-docs/contributing.md +++ /dev/null @@ -1,77 +0,0 @@ -## Issues - -Report issues and suggest features and improvements on the -[GitHub issue tracker](https://github.com/bbatsov/projectile/issues). Don't ask -questions on the issue tracker - use the [support channels](support.md) instead. - -If you want to file a bug, please provide all the necessary info listed in -our issue reporting template (it's loaded automatically when you create a -new GitHub issue). - -It's usually a good idea to try to reproduce (obscure) bugs in isolation. You -can do this by cloning Projectile's GitHub repo and running `make run-projectile` inside -it. This will bring up Emacs with only the latest version of Projectile loaded. By -starting fresh, with the latest code, we can ensure that the problem at hand -isn't already fixed or caused by interactions with other packages. - -## Patches - -Patches in any form are always welcome! GitHub pull requests are even better! :-) - -Before submitting a patch or a pull request make sure all tests are -passing and that your patch is in line with the [contribution -guidelines](https://github.com/bbatsov/projectile/blob/master/CONTRIBUTING.md). - -## Documentation - -Good documentation is just as important as good code. - -Consider improving and extending this manual and the -[community wiki](https://github.com/bbatsov/projectile/wiki). - -### Working on the Manual - -The manual is generated from the markdown files in the -[doc](https://github.com/bbatsov/projectile/tree/master/doc) folder of Projectile's -GitHub repo and is published to [Read the Docs](readthedocs.org). The -[MkDocs](http://www.mkdocs.org/) tool is used to convert the markdown sources to -HTML. - -To make changes to the manual you simply have to change the files under -`doc`. The manual will be regenerated automatically when changes to those files -are merged in `master` (or the latest stable branch). - -You can install `MkDocs` locally and use the command `mkdocs serve` to see the -result of changes you make to the manual locally: - -```sh -$ cd path/to/projectile/repo -$ mkdocs serve -``` - -If you want to make changes to the manual's page structure you'll have to edit -[mkdocs.yml](https://github.com/bbatsov/projectile/blob/master/mkdocs.yml). - -## Donations - -You can support the development of Projectile via -[PayPal](https://www.paypal.me/bbatsov), -[Patreon](https://www.patreon.com/bbatsov) and -[GitHub Sponsors](https://github.com/sponsors/bbatsov). - -## Running the tests in batch mode - -```sh -$ cd /path/to/projectile -$ make update -$ make compile -$ make test -``` - -Run all tests with: - -```sh -$ make test -``` - -Tests should run fine in `shell-mode` or `term-mode`. It's also possible to use M-x `compile` (or `helm-make`). diff --git a/legacy-docs/css/extra.css b/legacy-docs/css/extra.css deleted file mode 100644 index a12470945..000000000 --- a/legacy-docs/css/extra.css +++ /dev/null @@ -1,15 +0,0 @@ -/* By default kbd doesn't stand out very much. Let's fix this! */ -kbd { - padding: 3px 5px; - border: solid 1px #ccc; - background-color: #fcfcfc; - border-radius: 3px; - box-shadow: inset 0 -1px 0 #bbb; - display: inline-block; -} - -/* The default font-size for code blocks is 75% which makes code -hard to read. */ -code { - font-size: 90%; -} diff --git a/legacy-docs/extensions.md b/legacy-docs/extensions.md deleted file mode 100644 index 29891a5d0..000000000 --- a/legacy-docs/extensions.md +++ /dev/null @@ -1,8 +0,0 @@ -## Extensions - -There are a number of packages that built on top of the basic functionality provided by Projectile: - -* [counsel-projectile](https://github.com/ericdanan/counsel-projectile) provides Ivy integration -* [helm-projectile](https://github.com/bbatsov/helm-projectile) provides Helm integration -* [persp-projectile](https://github.com/bbatsov/persp-projectile) provides perspective.el integration -* [projectile-rails](https://github.com/asok/projectile-rails) provides extra functionality for Ruby on Rails projects diff --git a/legacy-docs/faq.md b/legacy-docs/faq.md deleted file mode 100644 index 0a20eb045..000000000 --- a/legacy-docs/faq.md +++ /dev/null @@ -1,27 +0,0 @@ -## 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](https://www.gnu.org/software/emacs/manual/html_node/elisp/Key-Binding-Conventions.html), -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. - -**Update** This was changed in Projectile 2.0. - -## Do you need some help cleanup up all those tickets that have piled up? - -Certainly! In our [issue -tracker](https://github.com/bbatsov/projectile/issues/) we've got -plenty of tickets marked with `Help Wanted` or `Good First Issue` that -you can take a stab at, if you'd like to help out! diff --git a/legacy-docs/index.md b/legacy-docs/index.md deleted file mode 100644 index 5d329f47c..000000000 --- a/legacy-docs/index.md +++ /dev/null @@ -1,66 +0,0 @@ -**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. - -Here's a glimpse of Projectile in action (find file in project using `ivy`): - -![Projectile Screenshot](screenshots/projectile-demo.gif) - -In this short demo you can see: - -* finding files in a project -* switching between implementation and test -* switching between projects - -Projectile provides easy project management and navigation. The -concept of a project is pretty basic - just a folder containing -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 -* 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 all project buffers -* replace in project -* multi-occur in project buffers -* grep in project -* regenerate project etags or gtags (requires [ggtags](https://github.com/leoliu/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 (e.g. `ido`, `ivy` and `helm`) - -!!! Info - - 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), - [Patreon](https://www.patreon.com/bbatsov) and - [GitHub Sponsors](https://github.com/sponsors/bbatsov). diff --git a/legacy-docs/installation.md b/legacy-docs/installation.md deleted file mode 100644 index d87c87042..000000000 --- a/legacy-docs/installation.md +++ /dev/null @@ -1,137 +0,0 @@ -## Prerequisites - -You'll need to have Emacs installed (preferably the latest stable -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). - -!!! Note - - Projectile officially supports Emacs 25.1+. - -## Installation - -The recommended way to install Projectile is via `package.el`. - -### Installation via package.el - -Projectile is available on the two major `package.el` community -maintained repos - -[MELPA Stable](http://stable.melpa.org) -and [MELPA](http://melpa.org). - -You can install Projectile with the following command: - -M-x package-install [RET] projectile [RET] - -or by adding this bit of Emacs Lisp code to your Emacs initialization file -(`.emacs` or `init.el`): - -```elisp -(unless (package-installed-p 'projectile) - (package-install 'projectile)) -``` - -If the installation doesn't work try refreshing the package list: - -M-x package-refresh-contents [RET] - -Keep in mind that MELPA packages are built automatically from -the `master` branch, meaning bugs might creep in there from time to -time. Never-the-less, installing from MELPA is a reasonable way of -obtaining Projectile, as the `master` branch is normally quite stable -and serious regressions there are usually fixed pretty quickly. - -!!! Tip - - If you don't want to (or can't) wait for MELPA to rebuild Projectile, - you can easily build and install an up-to-date MELPA package locally yourself. Check out - [this article](http://emacsredux.com/blog/2015/05/10/building-melpa-packages-locally/) - for details on the subject. - -Generally, users of the non-adventurous kind are advised to stick -with the stable releases, available from MELPA Stable. -You can pin Projectile to always use MELPA -Stable by adding this to your Emacs initialization: - -```elisp -(add-to-list 'package-pinned-packages '(projectile . "melpa-stable") t) -``` - -Finally add this to your Emacs config: - -```elisp -(require 'projectile) -(define-key projectile-mode-map (kbd "s-p") 'projectile-command-map) -(define-key projectile-mode-map (kbd "C-c p") 'projectile-command-map) -(projectile-mode +1) -``` - -!!! Note - - Those keymap prefixes are just a suggestion. Feel free to put - there whatever works best for you. - `C-c p` used to be the default prefix up to version 2.0, but - starting with version 2.0 you have to select prefix key(s) - yourself. - -### Installation via use-package - -`use-package` can be used to install Projectile via the `package.el`'s repositories -[MELPA Stable](http://stable.melpa.org) and [MELPA](http://melpa.org). - -If you wanted to install the version of Projectile which is what is to be found in -the `master` branch, declare the following in your Emacs initialization file -(`.emacs` or `init.el`): - -```elisp -(use-package projectile - :ensure t - :config - (define-key projectile-mode-map (kbd "s-p") 'projectile-command-map) - (define-key projectile-mode-map (kbd "C-c p") 'projectile-command-map) - (projectile-mode +1)) -``` - -However, if you wanted to be a bit more conservative and only use the stable -releases of Projectile, you'd declare the following: - -```elisp -(use-package projectile - :ensure t - :pin melpa-stable - :config - (define-key projectile-mode-map (kbd "s-p") 'projectile-command-map) - (define-key projectile-mode-map (kbd "C-c p") 'projectile-command-map) - (projectile-mode +1)) -``` - -After placing one of the above s-expressions, evaluate it, for it to take effect -by entering: C-x C-e. - -For further configuration options with `use-package`, consult the -official [use-package repository](https://github.com/jwiegley/use-package). - -### Installation via el-get - -Projectile is also available for installation from -the [el-get](https://github.com/dimitri/el-get) package manager. - -Provided you've already installed `el-get` you can install Projectile with the -following command: - -M-x el-get-install [RET] projectile [RET] - -### Installation on Debian and Ubuntu - -Users of Debian 9 or later or Ubuntu 16.10 or later may simply -`apt-get install elpa-projectile`. - -Your favourite Linux distribution might be providing a Projectile package as well. - -### Emacs Prelude - -Projectile is bundled with -[Emacs Prelude](https://github.com/bbatsov/prelude). If you're a Prelude -user, Projectile is already properly configured and ready for -action. diff --git a/legacy-docs/projects.md b/legacy-docs/projects.md deleted file mode 100644 index 32d8b619d..000000000 --- a/legacy-docs/projects.md +++ /dev/null @@ -1,424 +0,0 @@ -## Supported Project Types - -One of the main goals of Projectile is to operate on a wide range of project types -without the need for any configuration. To achieve this it contains a lot of -project detection logic and project type specific logic. - -### Version Control Systems - -Projectile considers most version-controlled repos to be -a project. Out of the box Projectile supports: - -* Git -* Mercurial -* Bazaar -* Subversion -* CVS -* Fossil -* Darcs - -### File markers - -Projectile considers many files to denote the root of a project. Usually those files -are the configuration files of various build tools. Out of the box the following are supported: - -File | Project Type -------------------|---------------------- -rebar.config | Rebar project file -project.clj | Leiningen project file -build.boot | Boot-clj project file -deps.edn | Clojure CLI project file -SConstruct | Scons project file -pom.xml | Maven project file -build.sbt | SBT project file -gradlew | Gradle wrapper script -build.gradle | Gradle project file -.ensime | Ensime configuration file -Gemfile | Bundler file -requirements.txt | Pip file -setup.py | Setuptools file -tox.ini | Tox file -composer.json | Composer project file -Cargo.toml | Cargo project file -mix.exs | Elixir mix project file -stack.yaml | Haskell's stack tool based project -info.rkt | Racket package description file -DESCRIPTION | R package description file -TAGS | etags/ctags are usually in the root of project -GTAGS | GNU Global tags -configure.in | autoconf old style -configure.ac | autoconf new style -cscope.out | cscope -Makefile | Make -WORKSPACE | Bazel workspace file - -There's also Projectile's own `.projectile` which serves both as a project marker -and a configuration file. We'll talk more about later in this section. - -## 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 - -```elisp -(projectile-register-project-type 'npm '("package.json") - :compile "npm install" - :test "npm test" - :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`. - 3. add *compile-command*, in this case it is `npm install`. - 4. add *test-command*, in this case it is `npm test`. - 5. add *run-command*, in this case it is `npm start`. - 6. add test files suffix for toggling between implementation/test files, in this case it is `.spec`, so the implementation/test file pair could be `service.js`/`service.spec.js` for example. - -The available options are: - -Option | Documentation -------------------|-------------------------------------------------------------------------------------------- -:compilation-dir | A path, relative to the project root, from where to run the tests and compilation commands. -:compile | A command to compile the project. -:configure | A command to configure the project. `%s` will be substituted with the project root. -:run | A command to run the project. -:src-dir | A path, relative to the project root, where the source code lives. -:test | A command to test the project. -:test-dir | A path, relative to the project root, where the test code lives. -:test-prefix | A prefix to generate test files names. -:test-suffix | A suffix to generate test files names. -:related-files-fn | A function to specify test/impl/other files in a more flexible way. - -#### Returning Projectile Commands from a function - -You can also pass a symbolic reference to a function into your project type definition if you wish to define the compile command dynamically: - -```elisp -(defun my/compile-command () - "Returns a String representing the compile command to run for the given context" - (cond - ((and (eq major-mode 'java-mode) - (not (string-match-p (regexp-quote "\\.*/test/\\.*") (buffer-file-name (current-buffer))))) - "./gradlew build") - ((eq major-mode 'web-mode) - "./gradlew compile-templates") - )) - -(defun my/test-command () - "Returns a String representing the test command to run for the given context" - (cond - ((eq major-mode 'js-mode) "grunt test") ;; Test the JS of the project - ((eq major-mode 'java-mode) "./gradlew test") ;; Test the Java code of the project - ((eq major-mode 'my-mode) "special-command.sh") ;; Even Special conditions/test-sets can be covered - )) - -(projectile-register-project-type 'has-command-at-point '("file.txt") - :compile 'my/compile-command - :test 'my/test-command) -``` - -If you would now navigate to a file that has the `*.java` extension under the `./tests/` directory and hit `C-c c p` you -will see `./gradlew build` as the suggestion. If you were to navigate to a HTML file the compile command will have switched -to `./gradlew compile-templates`. - -This works for: - - * `:configure` - * `:compile` - * `:compilation-dir` - * `:run` - -Note that your function has to return a string to work properly. - -### Related file location - -For simple projects, `:test-prefix` and `:test-suffix` option with string will -be enough to specify test prefix/suffix applicable regardless of file extensions -on any directory path. `projectile-other-file-alist` variable can be also set to -find other files based on the extension. - -For the full control of finding related files, `:related-files-fn` option with a -custom function or a list of custom functions can be used. The custom function -accepts the relative file name from the project root and it should return the -related file information as plist with the following optional key/value pairs: - -| Key | Value | Command applicable | -|--------|---------------------------------------------------------------|---------------------------------------------------------------------------------| -| :impl | matching implementation file if the given file is a test file | projectile-toggle-between-implementation-and-test, projectile-find-related-file | -| :test | matching test file if the given file has test files. | projectile-toggle-between-implementation-and-test, projectile-find-related-file | -| :other | any other files if the given file has them. | projectile-find-other-file, projectile-find-related-file | -| :foo | any key other than above | projectile-find-related-file | - - -For each value, following type can be used: - -| Type | Meaning | -|----------------------------|----------------------------------------------------------------------------------------------------------| -| string / a list of strings | Relative paths from the project root. The paths which actually exist on the file system will be matched. | -| a function | A predicate which accepts a relative path as the input and return t if it matches. | -| nil | No match exists. | - -Notes: - 1. For a big project consisting of many source files, returning strings instead - of a function can be fast as it does not iterate over each source file. - 2. There is a difference in behaviour between no key and `nil` value for the - key. Only when the key does not exist, other project options such as - `:test_prefix` or `projectile-other-file-alist` mechanism is tried. - - -#### Example - Same source file name for test and impl - -```elisp -(defun my/related-files (path) - (if (string-match (rx (group (or "src" "test")) (group "/" (1+ anything) ".cpp")) path) - (let ((dir (match-string 1 path)) - (file-name (match-string 2 path))) - (if (equal dir "test") - (list :impl (concat "src" file-name)) - (list :test (concat "test" file-name) - :other (concat "src" file-name ".def")))))) - -(projectile-register-project-type - ;; ... - :related-files-fn #'my/related-files) -``` - -With the above example, src/test directory can contain the same name file for test and its implementation file. -For example, "src/foo/abc.cpp" will match to "test/foo/abc.cpp" as test file and "src/foo/abc.cpp.def" as other file. - - -#### Example - Different test prefix per extension -A custom function for the project using multiple programming languages with different test prefixes. -```elisp -(defun my/related-files(file) - (let ((ext-to-test-prefix '(("cpp" . "Test") - ("py" . "test_")))) - (if-let ((ext (file-name-extension file)) - (test-prefix (assoc-default ext ext-to-test-prefix)) - (file-name (file-name-nondirectory file))) - (if (string-prefix-p test-prefix file-name) - (let ((suffix (concat "/" (substring file-name (length test-prefix))))) - (list :impl (lambda (other-file) - (string-suffix-p suffix other-file)))) - (let ((suffix (concat "/" test-prefix file-name))) - (list :test (lambda (other-file) - (string-suffix-p suffix other-file)))))))) -``` - -`projectile-find-related-file` command is also available to find and choose -related files of any kinds. For example, the custom function can specify the -related documents with ':doc' key. Note that `projectile-find-related-file` only -relies on `:related-files-fn` for now. - -### Related file custom function helper - -`:related-files-fn` can accept a list of custom functions to combine the result -of each custom function. This allows users to write several custom functions -and apply them differently to projects. - -Projectile includes a couple of helpers to generate commonly used custom functions. - -| Helper name and params | Purpose | -|------------------------------------|-------------------------------------------------------------| -| groups KIND GROUPS | Relates files in each group as the specified kind. | -| extensions KIND EXTENSIONS | Relates files with extensions as the specified kind. | -| tests-with-prefix EXTENSION PREFIX | Relates files with prefix and extension as :test and :impl. | -| tests-with-suffix EXTENSION SUFFIX | Relates files with suffix and extension as :test and :impl. | - -Each helper means `projectile-related-files-fn-helper-name` function. - -#### Example usage of projectile-related-files-fn-helpers -```elisp -(setq my/related-files - (list - (projectile-related-files-fn-extensions :other '("cpp" "h" "hpp")) - (projectile-related-files-fn-test-with-prefix "cpp" "Test") - (projectile-related-files-fn-test-with-suffix "el" "_test") - (projectile-related-files-fn-groups - :doc - '(("doc/common.txt" - "src/foo.h" - "src/bar.h"))))) - -(projectile-register-project-type - ;; ... - :related-files-fn #'my/related-files) -``` - -## Customizing project root files - -You can set the values of `projectile-project-root-files`, -`projectile-project-root-files-top-down-recurring`, -`projectile-project-root-files-bottom-up` and -`projectile-project-root-files-functions` to customize how project roots are -identified. - -To customize project root files settings: - -``` -M-x customize-group RET projectile RET -``` - -## Ignoring files - -!!! Warning - - The contents of `.projectile` are ignored when using the - `alien` project indexing method. - -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 -adding each path to ignore, where the paths all are relative to the -root directory and start with a slash. Everything ignored should be -preceded with a `-` sign. Alternatively, not having any prefix at all -also means to ignore the directory or file pattern that follows. -Here's an example for a typical Rails application: - -``` --/log --/tmp --/vendor --/public/uploads -``` - -This would ignore the folders only at the root of the project. -Projectile also supports relative pathname ignores: - -``` --tmp --*.rb --*.yml --models -``` - -You can also ignore everything except certain subdirectories. This is -useful when selecting the directories to keep is easier than selecting -the directories to ignore, although you can do both. To select -directories to keep, that means everything else will be ignored. - -Example: - -``` -+/src/foo -+/tests/foo -``` - -Keep in mind that you can only include subdirectories, not file -patterns. - -If both directories to keep and ignore are specified, the directories -to keep first apply, restricting what files are considered. The paths -and patterns to ignore are then applied to that set. - -Finally, you can override ignored files. This is especially useful -when some files ignored by your VCS should be considered as part of -your project by projectile: - -``` -!/src/foo -!*.yml -``` - -When a path is overridden, its contents are still subject to ignore -patterns. To override those files as well, specify their full path -with a bang prefix. - -If you would like to include comment lines in your .projectile file, -you can customize the variable `projectile-dirconfig-comment-prefix`. -Assigning it a non-nil character value, e.g. `#`, will cause lines in -the .projectile file starting with that character to be treated as -comments instead of patterns. - -### 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 -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 - -From project to project, some things may differ even in the same -language - coding styles, auto-completion sources, etc. If you need -to set some variables according to the selected project, you can use a -standard Emacs feature called -[Per-directory Local Variables](http://www.gnu.org/software/emacs/manual/html_node/emacs/Directory-Variables.html). -To use it you must create a file named `.dir-locals.el` (as specified -by the constant `dir-locals-file`) inside the project directory. This -file should contain something like this: - -```elisp -((nil . ((secret-ftp-password . "secret") - (compile-command . "make target-x") - (eval . (progn - (defun my-project-specific-function () - ;; ... - ))))) - (c-mode . ((c-file-style . "BSD")))) -``` - -The top-level alist member referenced with the key `nil` applies to -the entire project. A key with the name `eval` will evaluate its -corresponding value. In the example above, this is used to create a -function. It could also be used to e.g. add such a function to a key -map. - -You can also quickly visit or create the `dir-locals-file` with -s-p E (M-x projectile-edit-dir-locals RET). - -Here are a few examples of how to use this feature with Projectile. - -## Configuring Projectile's Behavior - -Projectile exposes many variables (via `defcustom`) which allow users -to customize its behavior. Directory variables can be used to set -these customizations on a per-project basis. - -You could enable caching for a project in this way: - -```elisp -((nil . ((projectile-enable-caching . t)))) -``` - -If one of your projects had a file that you wanted Projectile to -ignore, you would customize Projectile by: - -```elisp -((nil . ((projectile-globally-ignored-files . ("MyBinaryFile"))))) -``` - -If you wanted to wrap the git command that Projectile uses to list -the files in you repository, you could do: - -```elisp -((nil . ((projectile-git-command . "/path/to/other/git ls-files -zco --exclude-standard")))) -``` - -If you want to use a different project name than how Projectile named -your project, you could customize it with the following: - -```elisp -((nil . ((projectile-project-name . "your-project-name-here")))) -``` - -## Configure a Project's Compilation, Test and Run commands - -There are a few variables that are intended to be customized via `.dir-locals.el`. - -* for compilation - `projectile-project-compilation-cmd` -* for testing - `projectile-project-test-cmd` -* for running - `projectile-project-run-cmd` - -When these variables have their default value of `nil`, Projectile -runs the default command for the current project type. You can -override this behavior by setting them to either a string to run an -external command or an Emacs Lisp function: - -```elisp -(setq projectile-test-cmd #'custom-test-function) -``` diff --git a/legacy-docs/screenshots/projectile-demo.gif b/legacy-docs/screenshots/projectile-demo.gif deleted file mode 100644 index 1db2aec5e..000000000 Binary files a/legacy-docs/screenshots/projectile-demo.gif and /dev/null differ diff --git a/legacy-docs/screenshots/projectile.png b/legacy-docs/screenshots/projectile.png deleted file mode 100644 index d64dd1b78..000000000 Binary files a/legacy-docs/screenshots/projectile.png and /dev/null differ diff --git a/legacy-docs/support.md b/legacy-docs/support.md deleted file mode 100644 index 3f3c837ef..000000000 --- a/legacy-docs/support.md +++ /dev/null @@ -1,37 +0,0 @@ -Projectile currently has several official & unofficial support channels. - -For questions, suggestions and support refer to one of them. Please, don't -use the support channels to report issues, as this makes them harder to track. - -## Gitter - -Most internal discussions about the development of Projectile happen on its -[gitter channel](https://gitter.im/bbatsov/projectile). You can often find -Projectile's maintainers there and get some interesting news from the project's -kitchen. - -## Mailing List - -The [official mailing list](https://groups.google.com/forum/#!forum/projectile) is -hosted at Google Groups. It's a low-traffic list, so don't be too hesitant to subscribe. - -## Freenode - -If you're into IRC you can visit the `#projectile` channel on Freenode. -It's not actively -monitored by the Projectile maintainers themselves, but still you can get support -from other Projectile users there. - -## Stackoverflow - -We're also encouraging users to ask Projectile-related questions on StackOverflow. - -When doing so you should use the -[Projectile](http://stackoverflow.com/questions/tagged/projectile) tag (ideally combined -with the tag `emacs`). - -## Bountysource - -If you're willing to pay for some feature to be implemented you can use -[Bountysource](https://www.bountysource.com/teams/projectile/issues) to place a -bounty for the work you want to be done. diff --git a/legacy-docs/troubleshooting.md b/legacy-docs/troubleshooting.md deleted file mode 100644 index 9f64b5021..000000000 --- a/legacy-docs/troubleshooting.md +++ /dev/null @@ -1,63 +0,0 @@ -In case you run into issues here are a few tips that can help you diagnose the -problem. - -Generally, it's not a bad idea to configure Emacs to spit the backtrace on error -(instead of just logging the error in the `*Messages*` buffer). You can toggle -this behavior by using M-x `toggle-debug-on-error`. - -## Debugging Projectile commands - -Emacs features a super powerful built-in -[Emacs Lisp debugger](http://www.gnu.org/software/emacs/manual/html_node/elisp/Edebug.html) -and using it is the best way to diagnose problems of any kind. - -!!! Tip - - Here's a [great crash course](https://www.youtube.com/watch?v=odkYXXYOxpo) on - using the debugger. - -To debug some command you need to do the following: - -* Figure out the name of the command you want to debug (e.g. by using C-h k -to see which command is associated with some keybinding) -* Find the source of the command (e.g. by using M-x `find-function` - RET `function-name`) -* Press C-u C-M-x while in the body of the function -* Run the command again - -At this point you'll be dropped in the debugger and you can step forward until -you find the problem. - -## Profiling Projectile commands - -Emacs comes with a [built-in -profiler](https://www.gnu.org/software/emacs/manual/html_node/elisp/Profiling.html). Using -it is pretty simple: - -1. Start it with M-x `profiler-start`. -2. Invoke some commands. -3. Get the report with M-x `profiler-report`. - -!!! Tip - - If you intend to share the profiling results with someone it's a good idea to - save the report buffer to a file with C-x C-w. - -## Commonly encountered problems (and how to solve them) - -Sometimes a Projectile command might hang for a while (e.g. due to a bug or a -configuration issue). Such problems are super annoying, but are relatively easy -to debug. Here are a few steps you can take in such situations: - -* Do M-x `toggle-debug-on-quit` -* Reproduce the problem -* Hit C-g around 10 seconds into the hang - -This will bring up a backtrace with the entire function stack, including -function arguments. So you should be able to figure out what's going on (or at -least what's being required). - -### I upgraded Projectile using `package.el` and nothing changed - -Emacs doesn't load the new files, it only installs them on disk. To see the -effect of changes you have to restart Emacs. diff --git a/legacy-docs/usage.md b/legacy-docs/usage.md deleted file mode 100644 index fea695602..000000000 --- a/legacy-docs/usage.md +++ /dev/null @@ -1,151 +0,0 @@ -## Basic setup - -!!! Note - - Everything in this section assumes you've enabled `projectile-mode`. - -To add a project to Projectile's list of known projects, open a file -in the project. If you have a projects directory, you can tell -Projectile about all of the projects in it with the command `M-x -projectile-discover-projects-in-directory`. - -You can go one step further and set a list of folders which Projectile -is automatically going to check for projects: - -```elisp -(setq projectile-project-search-path '("~/projects/" "~/work/")) -``` - -!!! Tip - - If you're going to use the default `ido` completion it's - **extremely highly** recommended that you install the optional - [flx-ido package](https://github.com/lewang/flx), which provides a much - more powerful alternative to `ido`'s built-in `flex` matching. - -Check out the ["Configuration"](configuration.md) section of the manual -for a lot more information about configuring Projectile. - -## Basic Usage - -Just open some file in a version-controlled (e.g. `git`) or a project -(e.g. `maven`) directory that's recognized by Projectile and you're -ready for action. Projectile happens to recognize out of the box every common -VCS and many popular project types for various programming languages. -You can learn more about Projectile's notion of a project [here](projects.md). - -!!! Note - - The extent of the support for every VCS differs and Git is the best supported - one. Projectile supports some advanced features like working with Git submodules - and using `git-grep` instead GNU grep. - -You need to know only a handful of Projectile commands to start benefiting from it. - -* Find file in current project (s-p f) -* Switch project (s-p p) -* Grep in project (s-p s g) -* Replace in project (s-p r) -* Invoke a command via the Projectile Commander (s-p m) - -The next section lists many more commands, but the basics can get you pretty far. - -## Interactive Commands - -!!! Note - - Projectile doesn't have a default key prefix for its commands, but all the examples - in the manual assume you've opted for `s-p` (`super`-p). - -Here's a list of the interactive Emacs Lisp functions, provided by Projectile: - -Keybinding | Description --------------------|------------------------------------------------------------ -s-p f | Display a list of all files in the project. With a prefix argument it will clear the cache first. -s-p F | Display a list of all files in all known projects. -s-p g | Display a list of all files at point in the project. With a prefix argument it will clear the cache first. -s-p 4 f | Jump to a project's file using completion and show it in another window. -s-p 4 g | Jump to a project's file based on context at point and show it in another window. -s-p 5 f | Jump to a project's file using completion and show it in another frame. -s-p 5 g | Jump to a project's file based on context at point and show it in another frame. -s-p d | Display a list of all directories in the project. With a prefix argument it will clear the cache first. -s-p 4 d | Switch to a project directory and show it in another window. -s-p 5 d | Switch to a project directory and show it in another frame. -s-p T | Display a list of all test files(specs, features, etc) in the project. -s-p l | Display a list of all files in a directory (that's not necessarily a project) -s-p s g | Run grep on the files in the project. -M-- s-p s g | Run grep on `projectile-grep-default-files` in the project. -s-p v | Run `vc-dir` on the root directory of the project. -s-p V | Browse dirty version controlled projects. -s-p b | Display a list of all project buffers currently open. -s-p 4 b | Switch to a project buffer and show it in another window. -s-p 5 b | Switch to a project buffer and show it in another frame. -s-p 4 C-o | Display a project buffer in another window without selecting it. -s-p a | Switch between files with the same name but different extensions. -s-p 4 a | Switch between files with the same name but different extensions in other window. -s-p 5 a | Switch between files with the same name but different extensions in other frame. -s-p o | Runs `multi-occur` on all project buffers currently open. -s-p r | Runs interactive query-replace on all files in the projects. -s-p i | Invalidates the project cache (if existing). -s-p R | Regenerates the projects `TAGS` file. -s-p j | Find tag in project's `TAGS` file. -s-p k | Kills all project buffers. -s-p D | Opens the root of the project in `dired`. -s-p 4 D | Opens the root of the project in `dired` in another window. -s-p 5 D | Opens the root of the project in `dired` in another frame. -s-p e | Shows a list of recently visited project files. -s-p left | Switch to the previous project buffer. -s-p right | Switch to the next project buffer. -s-p E | Opens the root `dir-locals-file` of the project. -s-p s s | Runs `ag` on the project, performing a literal search. Requires the presence of `ag.el`. With a prefix argument it will perform a regex search. -s-p ! | Runs `shell-command` in the root directory of the project. -s-p & | Runs `async-shell-command` in the root directory of the project. -s-p C | Runs a standard configure command for your type of project. -s-p c | Runs a standard compilation command for your type of project. -s-p P | Runs a standard test command for your type of project. -s-p t | Toggle between an implementation file and its test file. -s-p 4 t | Jump to implementation or test file in other window. -s-p 5 t | Jump to implementation or test file in other frame. -s-p z | Adds the currently visited file to the cache. -s-p p | Display a list of known projects you can switch to. -s-p S | Save all project buffers. -s-p m | Run the commander (an interface to run commands with a single key). -s-p ESC | Switch to the most recently selected Projectile buffer. - -If you ever forget any of Projectile's keybindings just do a: - -s-p C-h - -It is possible to add additional commands to -`projectile-command-map` referenced by the prefix key in -`projectile-mode-map`. You can add multiple keymap prefix for all -commands. Here's an example that adds `super-,` as a command prefix: - -```elisp -(define-key projectile-mode-map (kbd "s-,") 'projectile-command-map) -``` - -You can also bind the `projectile-command-map` to any other map you'd -like (including the global keymap). - -!!! Tip - - For some common commands you might want to take a little shortcut and - leverage the fairly unused `Super` key (by default `Command` on Mac - keyboards and `Windows` on Win keyboards). - -Here's something you can -add to your Emacs config: - -```elisp -(define-key projectile-mode-map [?\s-d] 'projectile-find-dir) -(define-key projectile-mode-map [?\s-p] 'projectile-switch-project) -(define-key projectile-mode-map [?\s-f] 'projectile-find-file) -(define-key projectile-mode-map [?\s-g] 'projectile-grep) -``` - -!!! Note - - Note that the `Super` keybindings are not usable in Windows, as Windows - makes heavy use of such keybindings itself. Emacs - Prelude already adds those extra keybindings. diff --git a/mkdocs.yml b/mkdocs.yml index a8a59d45c..bdb5d0435 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -5,18 +5,5 @@ site_favicon: favicon.ico copyright: "Copyright (C) 2011-2020 Bozhidar Batsov and Projectile contributors" docs_dir: legacy-docs pages: -- Home: index.md -- Installation: installation.md -- Usage: usage.md -- Projects: projects.md -- Configuration: configuration.md -- Extensions: extensions.md -- FAQ: faq.md -- Troubleshooting: troubleshooting.md -- Contributing: contributing.md -- Support: support.md -extra_css: - - css/extra.css -markdown_extensions: - - admonition +- Blank: blank.md theme: readthedocs