From b8e672be14c09870eca3b96d27026cba621a3471 Mon Sep 17 00:00:00 2001 From: Eric Danan Date: Thu, 15 Sep 2016 16:28:44 +0200 Subject: [PATCH] update readme --- README.md | 25 ++++++++++++++++++++----- 1 file changed, 20 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index b67b138..03c74b0 100644 --- a/README.md +++ b/README.md @@ -2,18 +2,33 @@ # Description -This library tries to do something similar to `helm-projectile`, but using `ivy` instead of `helm`. The main function is `counsel-projectile`. +[Projectile](https://github.com/bbatsov/projectile) has native support for using [ivy](https://github.com/abo-abo/swiper) as its completion system. Counsel-projectile provides further ivy integration into projectile by taking advantage of ivy's mechanism to select from a list of actions and/or apply an action without leaving the comlpetion session. It is inspired by [helm-projectile](https://github.com/bbatsov/helm-projectile). # Installation -Install the package from `MELPA` or `el-get`, or clone this repository somewhere in your load path. +Install the package from [MELPA](https://melpa.org) or [el-get](https://github.com/dimitri/el-get), or clone this repository somewhere in your load path. + +# Basic setup + +You can use counsel-projectile (and in particular call the command `counsel-projectile` described below with C-c p SPC) without setting up anything. If you want counsel-projectile to install replacements for some standard projectile commands (see below again), add the following to your init file: + + (counsel-projectile-on) # Usage -The main function is `counsel-projectile`. It starts an `ivy-read` session with the list of `projectile` known projects as candidates. The current project, if any, comes first in this list. The default action switches to the selected project (therefore calling `projectile-switch-project-action`). There are several additional actions to switch project with a specific `projectile-switch-project-action` (eg `projectile-vc`). The action list can be customized since `ivy-read` is called with `:caller 'counsel-projectile`. +The main command `counsel-projectile`, and can be called with C-c p SPC (assuming the variable `projectile-keymap-prefix` has been left at its default value, C-c p). This command behaves differently depending on whether you call it from inside a project or not: +- If you are not inside a project, call the function `counsel-projectile-switch-project`. This uses ivy to display a list of all known projects and let you select a project to switch to. You can choose from a number of actions to be applied upon switching (using M-o or C-M-o, as usual with ivy). +- If you are inside a project, call the function `counsel-projectile-find-file-or-buffer`. This uses ivy to display a list of all project buffers and files. The project buffers are fontified, and the project files that are not currently open are shown as "virtual buffers" with a different font (as in the function `ivy-switch-buffer`). You can choose to visit the selected file or display the selected buffer in the current or another window. If you would rather switch to a different project, you can so with M-SPC. -In the action list, a new function `counsel-projectile-find-file` is used instead of the standard `projectile-find-file`. It simply proposes an additional action to find the file in another window (thus bringing together `projectile-find-file` and `projectile-find-file-other-window`). You may also call this function directly or bind it to some key. Similarly for two other new functions: `counsel-projectile-find-dir` and `counsel-projectile-switch-to-buffer`. +Counsel-projectile also provides replacements for several standard projectile commands, which take advantage of ivy to let you choose from several actions. To install these replacements, call the command `counsel-projectile-on`. Here are the currently defined replacements, with their default key-bindings: +- C-c p f `counsel-projectile-find-file`: find a project file, +- C-c p d `counsel-projectile-find-dir`: find a project directory, +- C-c p b `counsel-projectile-switch-to-buffer`: switch to a project buffer, +- C-c p p `counsel-projectile-switch-project`: switch to another project (see above). +If your default action for switching to a project (stored in the variable `projectile-switch-project-action`) is `projectile-find-file` (the default), then `counsel-projectile-on` also replaces it with `counsel-projectile-find-file-or-buffer` (see above). + +You can call the command `counsel-projectile-off` to undo all changes made by `counsel-projectile-on`. # Contributors -Many thanks to @abo-abo and @DamienCassou who encouraged and helped me to start this repository. \ No newline at end of file +Many thanks to [abo-abo](https://github.com/abo-abo) and [DamienCassou](https://github.com/DamienCassou) who encouraged and helped me to start this repository.