maciej/counsel-projectile
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

update readme

Browse source
This commit is contained in:
Eric Danan 2017-12-18 21:33:29 +01:00
parent e35de664aa
commit f0c867bc92
1 changed files with 216 additions and 23 deletions
Download patch file Download diff file Expand all files Collapse all files

239
README.org
View file

@ -1,5 +1,4 @@
#+TITLE: Counsel-projectile -- Ivy UI for Projectile
#+OPTIONS: num:nil
[[https://melpa.org/#/counsel-projectile][[[https://melpa.org/packages/counsel-projectile-badge.svg]]]]
@ -7,41 +6,235 @@
:PROPERTIES:
:CUSTOM_ID: description
:END:
[[https://github.com/bbatsov/projectile][Projectile]] has native support for using [[https://github.com/abo-abo/swiper][ivy]] 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 completion session. It is inspired by [[https://github.com/bbatsov/helm-projectile][helm-projectile]].
[[https://github.com/bbatsov/projectile][Projectile]] has native support for using [[https://github.com/abo-abo/swiper][ivy]] as its completion system. Counsel-projectile provides further ivy integration into projectile by taking advantage of ivy's support for selecting from a list of actions and applying an action without leaving the completion session. Concretely, counsel-projectile defines replacements for existing projectile commands as well as new commands that have no projectile counterparts. A minor mode is also provided that adds key bindings for all these commands on top of the projectile key bindings.
* News
:PROPERTIES:
:CUSTOM_ID: news
:END:
- [2017-12-18] New version ~0.2~. If you are upgrading from ~0.1~, please read [[#upgrading][here]] about important changes.
- [2016-04-12] First version ~0.1~.
* Installation
:PROPERTIES:
:CUSTOM_ID: installation
:END:
Install the package from [[https://melpa.org][MELPA]] or [[https://github.com/dimitri/el-get][el-get]], or clone this repository somewhere in your load path.
* Basic setup
:PROPERTIES:
:CUSTOM_ID: basic-setup
:END:
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:
#+BEGIN_SRC emacs-lisp
(counsel-projectile-on)
#+END_SRC
* Usage
:PROPERTIES:
:CUSTOM_ID: usage
:END:
The main command is ~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, it calls 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, it instead 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 / 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~.
** Getting started
:PROPERTIES:
:CUSTOM_ID: start
:END:
To turn on counsel-projectile mode, either call the command ~counsel-projectile-mode~ or use the Customize interface to toggle on the variable ~counsel-projectile-mode~. This will turn on projectile mode, thus enabling all projectile key bindings, and add the counsel-projectile key bindings on top of them.
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 s s~ ~counsel-projectile-ag~: search project files with ag,
- ~C-c p p~ ~counsel-projectile-switch-project~: switch to another project (see above).
The counsel-projectile key bindings either remap existing projectile commands to their counsel-projectile replacements (e.g. ~C-c p f~ now calls ~counsel-projectile-find-file~ instead of ~projectile-find-file~) or bind keys to counsel-projectile commands that have no projectile counterparts (e.g. ~C-c p SPC~ calls the command ~counsel-projectile~).
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~.
Calling the command ~counsel-projectile-mode~ once again or toggling off the variable ~counsel-projectile-mode~ disables the counsel-projectile key bindings and turns off projectile mode.
You can call the command ~counsel-projectile-off~ to undo all changes made by ~counsel-projectile-on~.
Note that if you turn on projectile mode but not counsel-projectile mode, the counsel-projectile commands can still be called with ~M-x~, only the key bindings for these commands are not enabled.
** Summary of interactive commands
:PROPERTIES:
:CUSTOM_ID: commands
:END:
Replacements for existing commands:
| Key binding | Command | Description |
|-------------+---------------------------------------+-----------------------------|
| ~C-c p p~ | ~counsel-projectile-switch-project~ | Switch project |
| ~C-c p f~ | ~counsel-projectile-find-file~ | Jump to a project file |
| ~C-c p d~ | ~counsel-projectile-find-dir~ | Jump to a project directory |
| ~C-c p b~ | ~counsel-projectile-switch-to-buffer~ | Jump to a project buffer |
| ~C-c p s g~ | ~counsel-projectile-grep~ | Search project with grep |
| ~C-c p s s~ | ~counsel-projectile-ag~ | Search project with ag |
New commands:
| Key binding | Command | Description |
|-------------+----------------------------------+-----------------------------------------------------|
| ~C-c p SPC~ | ~counsel-projectile~ | Jump to a project buffer or file, or switch project |
| ~C-c p s r~ | ~counsel-projectile-rg~ | Search project with rg |
| ~C-c p O~ | ~counsel-projectile-org-capture~ | Org-capture something into project |
** The ~counsel-projectile~ command
Default key binding: ~C-c p SPC~.
This command lets you quickly jump to a project buffer or file. It uses ivy to display in the minibuffer a list of all project buffers as well as all project files that are not currently visited by a buffer. Buffers are fontified according to their major mode and files are fontified as "virtual buffers", as in the command ~ivy-switch-buffer~. As in all ivy commands, you can use ~M-o~ / ~C-M-o~ + ~<key>~ to select from a list of actions to apply (or ~M-RET~ / ~C-M-REG~ to apply the default action) to the selected candidate:
| Key | Action |
|-----+-------------------------------------------------------------------------------------------------------------------------------------------------|
| ~o~ | Open buffer or file in current window (default action) |
| ~j~ | Open buffer or file in other window |
| ~x~ | Open file externally (does nothing for buffers) |
| ~r~ | Open file as root (does nothing for buffers) |
| ~m~ | Find file manually: call ~counsel-find-file~ from buffer or file's directory, allowing to acces files ignored by projectile or create new files |
| ~p~ | Switch project: call ~counsel-projectile-switch-project~ (see below) |
If not called inside a project, ~counsel-projectile~ first offers to select a project to switch to by calling ~counsel-projectile-switch-project~ (see below). Once you select a project and hit ~RET~, it lets you jump to a buffer or file in this project as described above.
** ~counsel-projectile-switch-project~
Default key binding: ~C-c p p~.
This command is a replacement for ~projectile-switch-project~. It adds the possibility to select from a list of switch-project actions to apply to the selected project:
| Key | Action |
|-------+---------------------------------------------------------------------------------------------------------------------------------------|
| ~o~ | Jump to a project buffer or file: call ~counsel-projectile~ (default action; see above) |
| ~f~ | Jump to a project file: call ~counsel-projectile-find-file~ (see below) |
| ~d~ | Jump to a project directory: call ~counsel-projectile-find-dir~ (see below) |
| ~b~ | Jump to a project buffer: call ~counsel-projectile-switch-to-buffer~ (see below) |
| ~m~ | Find file manually: call ~counsel-find-file~ from the project root, allowing to acces files ignored by projectile or create new files |
| ~S~ | Save all project buffers |
| ~k~ | Kill all project buffers |
| ~K~ | Remove project from the list of known projects |
| ~c~ | Run project compilation command |
| ~C~ | Run project configure command |
| ~E~ | Edit project directory-local variables |
| ~v~ | Open project in vc-dir / magit / monky |
| ~s g~ | Search project with grep: call ~counsel-projectile-grep~ (see below) |
| ~s s~ | Search project with ag: call ~counsel-projectile-ag~ (see below) |
| ~s r~ | Search project with rg: call ~counsel-projectile-rg~ (see below) |
| ~x s~ | Invoke shell from the project root |
| ~x e~ | Invoke eshell from the project root |
| ~x t~ | Invoke term from the project root |
| ~O~ | Org-capture something into project: call ~counsel-projectile-org-capture~ (see below) |
** ~counsel-projectile-find-file~
Default key binding: ~C-c p f~.
This command is a replacement for ~projectile-find-file~. It displays a list of all project files and offers several actions:
| Key | Action |
|-----+---------------------------------------------------------------------------------------------------------------------------------------|
| ~o~ | Open file in current window (default action) |
| ~j~ | Open file in other window |
| ~x~ | Open file externally (does nothing for buffers) |
| ~r~ | Open file as root (does nothing for buffers) |
| ~m~ | Find file manually: call ~counsel-find-file~ from file's directory, allowing to acces files ignored by projectile or create new files |
| ~p~ | Switch project: call ~counsel-projectile-switch-project~ (see above) |
** ~counsel-projectile-find-dir~
Default key binding: ~C-c p d~.
This command is a replacement for ~projectile-find-dir~. It displays a list of all project directories and offers several actions:
| Key | Action |
|-----+--------------------------------------------------------------------------------------------------------------------------------|
| ~o~ | Open directory with ~dired~ in current window (default action) |
| ~j~ | Open director with ~dired~ in other window |
| ~m~ | Find file manually: call ~counsel-find-file~ from directory, allowing to acces files ignored by projectile or create new files |
| ~p~ | Switch project: call ~counsel-projectile-switch-project~ (see above) |
** ~counsel-projectile-switch-to-buffer~
Default key binding: ~C-c p b~.
This command is a replacement for ~projectile-switch-to-buffer~. It displays a list of all project buffers and offers several actions:
| Key | Action |
|-----+-----------------------------------------------------------------------------------------------------------------------------------------|
| ~o~ | Open buffer in current window (default action) |
| ~j~ | Open buffer in other window |
| ~m~ | Find file manually: call ~counsel-find-file~ from buffer's directory, allowing to acces files ignored by projectile or create new files |
| ~p~ | Switch project: call ~counsel-projectile-switch-project~ (see above) |
** ~counsel-projectile-grep~
Default key binding: ~C-c p s g~.
This command is a replacement for ~projectile-grep~. It searches all project files with ~grep~, taking advantage of ivy's support for updating the list of candidates after each input (dynamic collections). Each canidate corresponds to a matching line in some project file, and there is only one action that opens that file at that line.
** ~counsel-projectile-ag~
Default key binding: ~C-c p s s~.
This command is a replacement for ~projectile-ag~. It is similar to ~counsel-projectile-grep~ (see above) but uses ~ag~ (the silver searcher) instead of ~grep~.
** ~counsel-projectile-rg~
Default key binding: ~C-c p s r~.
This command is similar to ~counsel-projectile-grep~ (see above) but uses ~rg~ (ripgrep) instead of ~grep~.
** ~counsel-projectile-org-capture~
Default key binding: ~C-c p O~.
This command lets you capture something (a note, todo item...) into the current project using org-mode's ~org-capture~. Like ~org-capture~, it first lets you select a capture template then file the newly captured information. By default, there is a single template storing the captured information into file \"notes.org\" in the project root directory, under headline ~Tasks~.
* Configuration
:PROPERTIES:
:CUSTOM_ID: config
:END:
** Enabling counsel-projectile mode when emacs starts
To automatically enable counsel-projectile mode when emacs starts, you can either use the Customize interface to toggle on the variable ~counsel-projectile-mode~ and save your customization, or add ~(counsel-projectile-mode)~ to your init file.
** Customizing action lists
:PROPERTIES:
:CUSTOM_ID: config/action
:END:
The lists of available actions (including the default action) for most of the commands above are stored in custom variables. If you set one of these variables, either through the Customize interface or directly with ~setq~, the new value will be picked up the next time you invoke the correspodiding commmand.
The variable holding the action list for ~command~ is named ~command-action~. The following action list variables are defined:
- ~counsel-projectile-action~
- ~counsel-projectile-switch-project-action~
- ~counsel-projectile-find-file-action~
- ~counsel-projectile-find-dir-action~
- ~counsel-projectile-switch-to-buffer-action~
For instance, the default value of ~counsel-projectile-action~ is:
#+BEGIN_SRC emacs-lisp
'(1
("o" counsel-projectile-action
"current window")
("j" counsel-projectile-action-other-window
"other window")
("x" counsel-projectile-action-file-extern
"open file externally")
("r" counsel-projectile-action-file-root
"open file as root")
("m" counsel-projectile-action-find-file-manually
"find file manually")
("p" (lambda (_) (counsel-projectile-switch-project))
"switch project"))
#+END_SRC
The first element is the index of the default action, and the remainig ones are the available actions (a key, an action function, and a name for each action). Thus the default action in this list is the first one ("current window").
Extra actions can be added to these lists or, alternatively, can be set through ivy's ~ivy-set-actions~ mechanism. If you prefer setting all actions (except the default one) through this mechanism, you can set the action list variable to a single action (e.g. ~'counsel-projectile-action~) instead of a list.
Note that ivy only supports one-character keys for actions. Hence, for instance, it is not possible to directly set the keys ~s g~, ~s s~, and ~s r~ for the three project search commands in ~projectile-switch-project-action~. Instead, the key ~s~ is set for a "prefix" action ~counsel-projectile-switch-project-action-prefix-search~ that reads a secondary one-character key and calls the corresponding search command as a "sub-action". The list of available sub-actions is read from the variable ~counsel-projectile-switch-project-action-prefix-search-sub-action~, which can be customized separately. This variable has the same format as an action list, except that the index is not present. Its default value is:
#+BEGIN_SRC emacs-lisp
'(("g" counsel-projectile-switch-project-action-grep
"Search project with grep")
("s" counsel-projectile-switch-project-action-ag
"Search project with ag")
("r" counsel-projectile-switch-project-action-rg
"Search project with rg"))
#+END_SRC
The following sub-action variables are defined:
- ~counsel-projectile-switch-project-action-prefix-search-sub-action~
- ~counsel-projectile-switch-project-action-prefix-shell-sub-action~
** Setting ~counsel-projectile-org-capture~ templates
The available capture templates for ~counsel-projectile-org-capture~ are read from the variable ~counsel-projectile-org-capture-templates~. This variable has the same format as the variable ~org-capture-templates~, except that in all strings of in an entry’s target slot, all instances of "${root}" and "${name}" are replaced with the current project root and name, respectively.
The default value contains a single template, whose target is:
#+BEGIN_SRC emacs-lisp
(file+headline "${root}/notes.org}" "Tasks")
#+END_SRC
This points to headline "Tasks" in file "notes.org" in the
project root directory (one file per project).
Another example of a valid target is:
#+BEGIN_SRC emacs-lisp
(file+olp "~/notes.org" "${root}" "Tasks")
#+END_SRC
(file+olp "~/notes.org" "${root}" "Tasks")
This points to outline path "<project-root>/Tasks" in file
"~/notes.org" (same file for all projects).
Templates contexts are read from the variable ~counsel-projectile-org-capture-templates-contexts~, which has the same format as ~capture-templates-contexts~
** Removing the current project or buffer from the list of candidates
By default, when calling ~counsel-projectile-switch-project~, the current project (if any) is included in the candidates list and preselected. Similarly, when calling ~counsel-projectile-switch-to-buffer~, the current buffer is included in the candidates list and preselected. If you prefer removing these elements from the candidate lists of these commands, you can set the variables ~counsel-projectile-remove-current-project~ and ~counsel-projectile-remove-current-buffer~ accordingly.
** Initial input for the project search commands
If you want some initial input to be inserted in the minibuffer every time you call ~counsel-projectile-grep~, ~counsel-projectile-ag~, or ~counsel-projectile-rg~, you can customize the variables ~counsel-projectile-grep-initial-input~, ~counsel-projectile-ag-initial-input~, or ~counsel-projectile-rg-initial-input~ accordingly. Each of these variable, if non ~nil~, should hold a Lisp expression whose evaluation yields the initial input string. If you use the Customize interface, some choices are proposed based on various versions of the ~thing-at-point~ function. Note that you can always insert the value of ~(ivy-thing-at-point)~ by hitting ~M-n~ in the minibuffer.
* Upgrading from previous version (~0.1~)
:PROPERTIES:
:CUSTOM_ID: upgrading
:END:
If you are upgrading from version ~0.1~ to version ~0.2~, please read below about important changes, some of which may require you to update your configuration.
** Key bindings
The commands ~counsel-projectile-on~, ~counsel-projectile-off~ and ~counsel-projectile-toggle~ no longer exist. They are replaced by the counsel-projectile minor mode. You can toggle this mode either by calling the ~counsel-projectile-mode~ command. or by setting the ~counsel-projectile-mode~ variable throught the Customize interface. See [[#start][Getting started]] above for details.
** Action lists
The available actions for the various counsel-projectile commands are now customized differently:
- The custom variable corresponding to ~command~ is now named ~command-action~, not ~command-actions~.
- This variable now stores all the available actions, including the default action, not only the extra actions.
- It also stores the index of the default action (it is a list whose first element is this index and whose remaining elements are the availabe actions).
- This variable is now used as the value of the ~:action~ parameter for the command's ~ivy-read~ call. Hence if you set it outside the Customize interface, you no longer need to call ~ivy-set-actions~ afterwards. If you set extra actions through ~ivy-set-actions~, they will not replace the variable's actions but will rather be added to them.
See [[#config/action][Customizing action lists]] above for details.
Also, in the default action lists, the keys set for some actions have changed, mainly for the ~counsel-projectile-switch-project~ command. Indeed, as new actions were added to this command, the corresponding list of keys was becoming somewhat inconsistent. The new keys replicate the default projectile key bindings (for instance, the aciton to save all project buffers is now called with the key ~S~, mimicking the default key binding ~C-c p S~ for the command ~projectile-save-project-buffers~). When an action calls a command that has no default projectile key binding, its key is chosen among those that are not bound by projectile by default.
** Minibuffer keymap
The minibuffer keymap ~counsel-projectile-map~ no longer exists. It was only used to bind a key (~M-SPC~ by default) to the command ~counsel-projectile-drop-to-switch-project~ exiting the current command and calling ~counsel-projectile-switch-project~. The same functionality is now implemented in a simpler way through an aciton that calls ~counsel-projectile-switch-project~, whose key is ~p~ by default. Concretely, you should now hit ~M-o p~ instead of ~M-SPC~.
* Contributors
:PROPERTIES:
:CUSTOM_ID: contributors
:END:
Many thanks to [[https://github.com/abo-abo][abo-abo]] and [[https://github.com/DamienCassou][DamienCassou]] who encouraged and helped me to start this repository.
Counsel-projectile is inspired by [[https://github.com/bbatsov/helm-projectile][helm-projectile]]. Many thanks to [[https://github.com/abo-abo][abo-abo]] and [[https://github.com/DamienCassou][DamienCassou]] who encouraged and helped me to start this repository, as well as all contributors and users who have submitted issues and pull requests.