diff --git a/CHANGELOG.md b/CHANGELOG.md index 73529510c..dd6f7499c 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,8 +9,9 @@ ### Changes * Handle files with special characters in `projectile-get-other-files` -* * [#1260](https://github.com/bbatsov/projectile/pull/1260): ignored-*-p: Now they match against regular expressions. -* **(Breaking)** Change the prefix for the Projectile mode commands to `C-c C-p`. +* [#1260](https://github.com/bbatsov/projectile/pull/1260): ignored-*-p: Now they match against regular expressions. +* **(Breaking)** Remove the default prefix key (`C-c p`) for Projectile. Users now have to pick one themselves. +* Deprecate `projectile-keymap-prefix`. * Avoid "No projects needed to be removed." messages in global mode ## 1.0.0 (2018-07-21) diff --git a/README.md b/README.md index a540b61ab..d09f5d61a 100644 --- a/README.md +++ b/README.md @@ -82,9 +82,19 @@ You can install Projectile with the following command: Alternatively, users of Debian 9 or later or Ubuntu 16.04 or later may simply `apt-get install elpa-projectile`. +Finally add this to your Emacs config: + +```el +(projectile-mode +1) +(define-key projectile-mode-map (kbd "s-p") 'projectile-command-map) +(define-key projectile-mode-map (kbd "C-c p") 'projectile-command-map) +``` + +Those keymap prefixes are just a suggestion. Feel free to put there whatever works best for you. + ### Basic Usage -Enable `projectile-mode`, open a file in one of your projects and type a command such as C-c C-p f. +Enable `projectile-mode`, open a file in one of your projects and type a command such as C-c p f. See the user manual for more details. diff --git a/doc/configuration.md b/doc/configuration.md index 8329bb30c..6bab18968 100644 --- a/doc/configuration.md +++ b/doc/configuration.md @@ -45,12 +45,12 @@ To enable caching unconditionally use this snippet of code: (setq projectile-enable-caching t) ``` -At this point you can try out a Projectile command such as C-c C-p f (M-x projectile-find-file RET). +At this point you can try out a Projectile command such as s-p f (M-x projectile-find-file RET). -Running C-u C-c C-p f will invalidate the cache prior to +Running C-u s-p f will invalidate the cache prior to prompting you for a file to jump to. -Pressing C-c C-p z will add the currently visited file to the +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. @@ -101,7 +101,7 @@ This might not be a great idea if you start Projectile in your home folder for i ## Switching projects -When running `projectile-switch-project` (C-c C-p p) Projectile invokes +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`). @@ -317,7 +317,7 @@ 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 -C-c C-p E (M-x projectile-edit-dir-locals RET). +s-p E (M-x projectile-edit-dir-locals RET). Here are a few examples of how to use this feature with Projectile. diff --git a/doc/installation.md b/doc/installation.md index 48f5b9479..a6b7bdbf8 100644 --- a/doc/installation.md +++ b/doc/installation.md @@ -58,6 +58,22 @@ Stable by adding this to your Emacs initialization: (add-to-list 'package-pinned-packages '(projectile . "melpa-stable") t) ``` +Finally add this to your Emacs config: + +```el +(projectile-mode +1) +(define-key projectile-mode-map (kbd "s-p") 'projectile-command-map) +(define-key projectile-mode-map (kbd "C-c p") 'projectile-command-map) +``` + +Those keymap prefixes are just a suggestion. Feel free to put there whatever works best for you. + +!!! Note + + `C-c p` used to be the default prefix up to version 1.1, but + starting with version 1.1 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 @@ -72,6 +88,7 @@ the `master` branch, declare the following in your Emacs initialization file :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)) ``` @@ -84,6 +101,7 @@ releases of Projectile, you'd declare the following: :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)) ``` diff --git a/doc/usage.md b/doc/usage.md index 1f5ccf201..21346705d 100644 --- a/doc/usage.md +++ b/doc/usage.md @@ -23,77 +23,72 @@ more powerful alternative to `ido`'s built-in `flex` matching. ## 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`. + Here's a list of the interactive Emacs Lisp functions, provided by Projectile: Keybinding | Description -------------------|------------------------------------------------------------ -C-c C-p f | Display a list of all files in the project. With a prefix argument it will clear the cache first. -C-c C-p F | Display a list of all files in all known projects. -C-c C-p g | Display a list of all files at point in the project. With a prefix argument it will clear the cache first. -C-c C-p 4 f | Jump to a project's file using completion and show it in another window. -C-c C-p 4 g | Jump to a project's file based on context at point and show it in another window. -C-c C-p 5 f | Jump to a project's file using completion and show it in another frame. -C-c C-p 5 g | Jump to a project's file based on context at point and show it in another frame. -C-c C-p d | Display a list of all directories in the project. With a prefix argument it will clear the cache first. -C-c C-p 4 d | Switch to a project directory and show it in another window. -C-c C-p 5 d | Switch to a project directory and show it in another frame. -C-c C-p T | Display a list of all test files(specs, features, etc) in the project. -C-c C-p l | Display a list of all files in a directory (that's not necessarily a project) -C-c C-p s g | Run grep on the files in the project. -M-- C-c C-p s g | Run grep on `projectile-grep-default-files` in the project. -C-c C-p v | Run `vc-dir` on the root directory of the project. -C-c C-p V | Browse dirty version controlled projects. -C-c C-p b | Display a list of all project buffers currently open. -C-c C-p 4 b | Switch to a project buffer and show it in another window. -C-c C-p 5 b | Switch to a project buffer and show it in another frame. -C-c C-p 4 C-o | Display a project buffer in another window without selecting it. -C-c C-p a | Switch between files with the same name but different extensions. -C-c C-p 4 a | Switch between files with the same name but different extensions in other window. -C-c C-p 5 a | Switch between files with the same name but different extensions in other frame. -C-c C-p o | Runs `multi-occur` on all project buffers currently open. -C-c C-p r | Runs interactive query-replace on all files in the projects. -C-c C-p i | Invalidates the project cache (if existing). -C-c C-p R | Regenerates the projects `TAGS` file. -C-c C-p j | Find tag in project's `TAGS` file. -C-c C-p k | Kills all project buffers. -C-c C-p D | Opens the root of the project in `dired`. -C-c C-p 4 D | Opens the root of the project in `dired` in another window. -C-c C-p 5 D | Opens the root of the project in `dired` in another frame. -C-c C-p e | Shows a list of recently visited project files. -C-c C-p E | Opens the root `dir-locals-file` of the project. -C-c C-p s s | Runs `ag` on the project. Requires the presence of `ag.el`. -C-c C-p ! | Runs `shell-command` in the root directory of the project. -C-c C-p & | Runs `async-shell-command` in the root directory of the project. -C-c C-p C | Runs a standard configure command for your type of project. -C-c C-p c | Runs a standard compilation command for your type of project. -C-c C-p P | Runs a standard test command for your type of project. -C-c C-p t | Toggle between an implementation file and its test file. -C-c C-p 4 t | Jump to implementation or test file in other window. -C-c C-p 5 t | Jump to implementation or test file in other frame. -C-c C-p z | Adds the currently visited file to the cache. -C-c C-p p | Display a list of known projects you can switch to. -C-c C-p S | Save all project buffers. -C-c C-p m | Run the commander (an interface to run commands with a single key). -C-c C-p ESC | Switch to the most recently selected Projectile buffer. +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 E | Opens the root `dir-locals-file` of the project. +s-p s s | Runs `ag` on the project. Requires the presence of `ag.el`. +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: -C-c C-p C-h - -You can change the default keymap prefix `C-c C-p` like this: - -```el -(setq projectile-keymap-prefix (kbd "C-c p")) -``` - -!!! Note - - `C-c p` used to be the default prefix up to version 1.1. +s-p C-h -It is also possible to add additional commands to +It is possible to add additional commands to `projectile-command-map` referenced by the prefix key in `projectile-mode-map`. You can even add an alternative prefix for all -commands. Here's an example that adds `super-p` as the extra prefix: +commands. Here's an example that adds `super-p` as a command prefix: ```el (define-key projectile-mode-map (kbd "s-p") 'projectile-command-map) diff --git a/projectile.el b/projectile.el index a10de3b1b..040cd2efb 100644 --- a/projectile.el +++ b/projectile.el @@ -148,11 +148,13 @@ Otherwise consider the current directory the project root." (const :tag "Default" default) (function :tag "Custom function"))) -(defcustom projectile-keymap-prefix (kbd "C-c C-p") +(defcustom projectile-keymap-prefix nil "Projectile keymap prefix." :group 'projectile :type 'string) +(make-obsolete-variable 'projectile-keymap-prefix "Use (define-key projectile-mode-map (kbd ...) 'projectile-command-map) instead." "1.1.0") + (defcustom projectile-cache-file (expand-file-name "projectile.cache" user-emacs-directory) "The name of Projectile's cache file." @@ -3959,7 +3961,8 @@ is chosen." (defvar projectile-mode-map (let ((map (make-sparse-keymap))) - (define-key map projectile-keymap-prefix 'projectile-command-map) + (when projectile-keymap-prefix + (define-key map projectile-keymap-prefix 'projectile-command-map)) map) "Keymap for Projectile mode.")