Table of Contents
- Description
- News
- Installation
- Usage
- Getting started
- Summary of interactive commands
- The
counsel-projectilecommand - The
counsel-projectile-switch-projectcommand - The
counsel-projectile-find-filecommand - The
counsel-projectile-find-dircommand - The
counsel-projectile-switch-to-buffercommand - The
counsel-projectile-grepcommand - The
counsel-projectile-agcommand - The
counsel-projectile-rgcommand - The
counsel-projectile-org-capturecommand
- Configuration
- Upgrading from previous version
- Contributors
Projectile has native support for using 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.
- [2018-01-05] Package now available on MELPA Stable.
- [2017-12-18] New version
0.2. If you are upgrading from0.1, please read here about important changes. - [2016-04-12] First version
0.1.
Install the package from MELPA, MELPA Stable, or el-get, or clone this repository somewhere in your load path.
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.
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).
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.
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.
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 into project |
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-RET 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 |
| 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.
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 |
| 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 into project: call counsel-projectile-org-capture (see below) |
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 |
| p | Switch project: call counsel-projectile-switch-project (see above) |
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 |
| p | Switch project: call counsel-projectile-switch-project (see above) |
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 |
| p | Switch project: call counsel-projectile-switch-project (see above) |
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.
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.
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.
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 (actually counsel-org-capture) command. 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.
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.
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 directly or through the through the Customize interface, the new value will be picked up the next time you invoke the corresponding commmand.
The variable holding the action list for <command> is named <command>-action. The following action list variables are defined:
counsel-projectile-actioncounsel-projectile-switch-project-actioncounsel-projectile-find-file-actioncounsel-projectile-find-dir-actioncounsel-projectile-switch-to-buffer-action
For instance, the default value of counsel-projectile-action is:
'(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"))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 (o key).
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. If you are not using the Customize interface and want to amend the value of one of these lists rather than setting it from scratch, you can use the function counsel-projectile-modify-action, which lets you easily:
- add, remove, or move an action,
- change an action key, function, or name,
- change the index of the default action. See its docstring for details.
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:
(file+headline "${root}/notes.org}" "Tasks")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:
(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 org-capture-templates-contexts
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.
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.
By default, the command counsel-projectile-find-file relies on the the matcher of the command counsel-find-file to display files matching minibuffer input, allowing to ignore some files based on the variable counsel-find-file-ignore-regexp. It is possible to use another matcher by setting the variable counsel-projectile-find-file-matcher. Some choices are proposed if you use the Customize interface, in particular the counsel-projectile-find-file-matcher-basename matcher which is provided by counsel-projectile and only displays files whose basename matches the minibuffer input (if there is none, it shows all matching files).
The matcher specified by counsel-find-file-ignore-regexp is also used by counsel-projectile to match files.
The following commands allow to modify the way candidates are sorted:
counsel-projectilecousnel-projectile-switch-projectcounsel-projectile-find-filecounsel-projectile-find-dircounsel-projectile-switch-to-bufferTo do so you need to add sorting functions toivy-sort-functions-alist, e.g.
(setcdr (assoc 'counsel-projectile-find-file ivy-sort-functions-alist)
'file-newer-than-file-p)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.
The commands counsel-projectile-on, counsel-projectile-off and counsel-projectile-toggle no longer exist. They are replaced with 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 Getting started above for details.
The available actions for the various counsel-projectile commands are now customized differently:
- The custom variable corresponding to
<command>is now named<command-action>instead of<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
:actionparameter for the command'sivy-readcall. Hence if you set it outside the Customize interface, you no longer need to callivy-set-actionsafterwards. If you set extra actions throughivy-set-actions, they will not replace the variable's actions but will be added to them.
See 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 action 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.
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 action that calls counsel-projectile-switch-project, whose key is p by default. Concretely, you should now hit M-o p instead of M-SP.
Counsel-projectile is inspired by helm-projectile. Many thanks to abo-abo and DamienCassou who encouraged and helped me to start this repository, as well as all contributors and users who have submitted issues and pull requests.