README.md (10442B)
1 # multiple-cursors.el [](http://travis-ci.org/magnars/multiple-cursors.el) 2 3 Multiple cursors for Emacs. This is some pretty crazy functionality, so yes, 4 there are kinks. Don't be afraid tho, I've been using it since 2011 with 5 great success and much merriment. 6 7 ## Installation 8 9 I highly recommend installing multiple-cursors through `package.el`. 10 11 It's available on [melpa](http://melpa.milkbox.net/): 12 13 M-x package-install multiple-cursors 14 15 The package depends on the `cl-lib` package, so if you do not use 16 `package.el` or have a recent Emacs, you would need to install that 17 too: see [GNU ELPA](http://elpa.gnu.org/packages/cl-lib.html). 18 19 ## Basic usage 20 21 Start out with: 22 23 (require 'multiple-cursors) 24 25 Then you have to set up your keybindings - multiple-cursors doesn't presume to 26 know how you'd like them laid out. Here are some examples: 27 28 When you have an active region that spans multiple lines, the following will 29 add a cursor to each line: 30 31 (global-set-key (kbd "C-S-c C-S-c") 'mc/edit-lines) 32 33 When you want to add multiple cursors not based on continuous lines, but based on 34 keywords in the buffer, use: 35 36 (global-set-key (kbd "C->") 'mc/mark-next-like-this) 37 (global-set-key (kbd "C-<") 'mc/mark-previous-like-this) 38 (global-set-key (kbd "C-c C-<") 'mc/mark-all-like-this) 39 40 First mark the word, then add more cursors. 41 42 To get out of multiple-cursors-mode, press `<return>` or `C-g`. The latter will 43 first disable multiple regions before disabling multiple cursors. If you want to 44 insert a newline in multiple-cursors-mode, use `C-j`. 45 46 ## Video 47 48 You can [watch an intro to multiple-cursors at Emacs Rocks](http://emacsrocks.com/e13.html). 49 50 ## Command overview 51 52 ### Mark one more occurrence 53 54 - `mc/mark-next-like-this`: Adds a cursor and region at the next part of the buffer forwards that matches the current region. 55 - `mc/mark-next-like-this-word`: Adds a cursor and region at the next part of the buffer forwards that matches the current region, if no region is selected it selects the word at the point. 56 - `mc/mark-next-like-this-symbol`: Adds a cursor and region at the next part of the buffer forwards that matches the current region, if no region is selected it selects the symbol at the point. 57 - `mc/mark-next-word-like-this`: Like `mc/mark-next-like-this` but only for whole words. 58 - `mc/mark-next-symbol-like-this`: Like `mc/mark-next-like-this` but only for whole symbols. 59 - `mc/mark-previous-like-this`: Adds a cursor and region at the next part of the buffer backwards that matches the current region. 60 - `mc/mark-previous-word-like-this`: Like `mc/mark-previous-like-this` but only for whole words. 61 - `mc/mark-previous-symbol-like-this`: Like `mc/mark-previous-like-this` but only for whole symbols. 62 - `mc/mark-more-like-this-extended`: Use arrow keys to quickly mark/skip next/previous occurances. 63 - `mc/add-cursor-on-click`: Bind to a mouse event to add cursors by clicking. See tips-section. 64 - `mc/mark-pop`: Set a cursor at the current point and move to the next (different) position on the mark stack. This allows for fine grained control over the placement of cursors. 65 66 ### Juggle around with the current cursors 67 68 - `mc/unmark-next-like-this`: Remove the cursor furthest down in the buffer. 69 - `mc/unmark-previous-like-this`: Remove the cursor furthest up in the buffer. 70 - `mc/skip-to-next-like-this`: Remove the cursor furthest down, marking the next occurance down. 71 - `mc/skip-to-previous-like-this`: Remove the cursor furthest up, marking the next occurance up. 72 - `mc/mark-next-like-this-extended`: Temporarily bind the arrow keys to mark/unmark/skip cursors. 73 74 ### Mark many occurrences 75 76 - `mc/edit-lines`: Adds one cursor to each line in the current region. 77 - `mc/edit-beginnings-of-lines`: Adds a cursor at the start of each line in the current region. 78 - `mc/edit-ends-of-lines`: Adds a cursor at the end of each line in the current region. 79 - `mc/mark-all-like-this`: Marks all parts of the buffer that matches the current region. 80 - `mc/mark-all-words-like-this`: Like `mc/mark-all-like-this` but only for whole words. 81 - `mc/mark-all-symbols-like-this`: Like `mc/mark-all-like-this` but only for whole symbols. 82 - `mc/mark-all-in-region`: Prompts for a string to match in the region, adding cursors to all of them. 83 - `mc/mark-all-like-this-in-defun`: Marks all parts of the current defun that matches the current region. 84 - `mc/mark-all-words-like-this-in-defun`: Like `mc/mark-all-like-this-in-defun` but only for whole words. 85 - `mc/mark-all-symbols-like-this-in-defun`: Like `mc/mark-all-like-this-in-defun` but only for whole symbols. 86 - `mc/mark-all-dwim`: Tries to be smart about marking everything you want. Can be pressed multiple times. 87 88 ### Special 89 90 - `set-rectangular-region-anchor`: Think of this one as `set-mark` except you're marking a rectangular region. 91 - `mc/mark-sgml-tag-pair`: Mark the current opening and closing tag. 92 - `mc/insert-numbers`: Insert increasing numbers for each cursor, top to bottom. 93 - `mc/insert-letters`: Insert increasing letters for each cursor, top to bottom. 94 - `mc/sort-regions`: Sort the marked regions alphabetically. 95 - `mc/reverse-regions`: Reverse the order of the marked regions. 96 97 ## Tips and tricks 98 99 - To get out of multiple-cursors-mode, press `<return>` or `C-g`. The latter will 100 first disable multiple regions before disabling multiple cursors. If you want to 101 insert a newline in multiple-cursors-mode, use `C-j`. 102 103 - Sometimes you end up with cursors outside of your view. You can 104 scroll the screen to center on each cursor with `C-v` and `M-v` or you can 105 press `C-'` to hide all lines without a cursor, press `C-'` again to unhide. 106 107 - Try pressing `mc/mark-next-like-this` with no region selected. It 108 will just add a cursor on the next line. 109 110 - Try pressing `mc/mark-next-like-this-word` or 111 `mc/mark-next-like-this-symbol` with no region selected. It will 112 mark the word or symbol and add a cursor at the next occurance 113 114 - Try pressing `mc/mark-all-like-this-dwim` on a tagname in html-mode. 115 116 - Notice that the number of cursors active can be seen in the modeline. 117 118 - If you get out of multiple-cursors-mode and yank - it will yank only 119 from the kill-ring of main cursor. To yank from the kill-rings of 120 every cursor use yank-rectangle, normally found at C-x r y. 121 122 - You can use `mc/reverse-regions` with nothing selected and just one cursor. 123 It will then flip the sexp at point and the one below it. 124 125 - When you use `mc/edit-lines`, you can give it a positive or negative 126 prefix to change how it behaves on too short lines. 127 128 - If you would like to keep the global bindings clean, and get custom keybindings 129 when the region is active, you can try [region-bindings-mode](https://github.com/fgallina/region-bindings-mode). 130 131 BTW, I highly recommend adding `mc/mark-next-like-this` to a key binding that's 132 right next to the key for `er/expand-region`. 133 134 ### Binding mouse events 135 136 To override a mouse event, you will likely have to also unbind the 137 `down-mouse` part of the event. Like this: 138 139 (global-unset-key (kbd "M-<down-mouse-1>")) 140 (global-set-key (kbd "M-<mouse-1>") 'mc/add-cursor-on-click) 141 142 Or you can do like me and find an unused, but less convenient, binding: 143 144 (global-set-key (kbd "C-S-<mouse-1>") 'mc/add-cursor-on-click) 145 146 ## Unknown commands 147 148 Multiple-cursors uses two lists of commands to know what to do: the run-once list 149 and the run-for-all list. It comes with a set of defaults, but it would be beyond silly 150 to try and include all the known Emacs commands. 151 152 So that's why multiple-cursors occasionally asks what to do about a command. It will 153 then remember your choice by saving it in `~/.emacs.d/.mc-lists.el`. You can change 154 the location with: 155 156 (setq mc/list-file "/my/preferred/file") 157 158 NB! Make sure to do so before requiring multiple-cursors. 159 160 ## Known limitations 161 162 * isearch-forward and isearch-backward aren't supported with multiple cursors. 163 If you want this functionality, you can use [phi-search](https://github.com/zk-phi/phi-search). 164 * Commands run with `M-x` won't be repeated for all cursors. 165 * All key bindings that refer to lambdas are always run for all cursors. If you 166 need to limit it, you will have to give it a name. 167 * Redo might screw with your cursors. Undo works very well. 168 169 170 ## Contribute 171 172 Yes, please do. There's a suite of tests, so remember to add tests for your 173 specific feature, or I might break it later. 174 175 You'll find the repo at: 176 177 https://github.com/magnars/multiple-cursors.el 178 179 To fetch the test dependencies, install 180 [cask](https://github.com/rejeep/cask.el) if you haven't already, 181 then: 182 183 $ cd /path/to/multiple-cursors 184 $ cask 185 186 Run the tests with: 187 188 $ ./run-tests.sh 189 190 ## Contributors 191 192 * [Takafumi Arakaki](https://github.com/tkf) has contributed several small improvements 193 * [Marco Baringer](https://github.com/segv) contributed looping to `mc/cycle` and adding cursors without region for mark-more. 194 * [Ivan Andrus](https://github.com/gvol) added showing number of cursors in mode-line, and different options for how to handle short lines in `mc/edit-lines`. 195 * [Fuco](https://github.com/Fuco1) added the first version of `mc/mark-all-like-this-dwim` 196 * [Zach Kost-Smith](https://github.com/smithzvk) added `mc/mark-pop` 197 * [Maciej Katafiasz](https://github.com/mathrick) added `mc/mark-all-dwim` 198 * [Aleksey Fedotov](https://github.com/lexa) added `mc-hide-unmatched-lines-mode` 199 * [Jules Tamagnan](https://github.com/jtamagnan) added `mc/mark-next-like-this-word` and `mc/mark-next-like-this-symbol` 200 * [Ingo Lohmar](https://github.com/ilohmar) extended `mc/add-cursor-on-click` to toggle cursors. 201 202 Thanks! 203 204 ## License 205 206 Copyright (C) 2012 Magnar Sveen 207 208 Author: Magnar Sveen <magnars@gmail.com> 209 Keywords: editing cursors 210 211 This program is free software; you can redistribute it and/or modify 212 it under the terms of the GNU General Public License as published by 213 the Free Software Foundation, either version 3 of the License, or 214 (at your option) any later version. 215 216 This program is distributed in the hope that it will be useful, 217 but WITHOUT ANY WARRANTY; without even the implied warranty of 218 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 219 GNU General Public License for more details. 220 221 You should have received a copy of the GNU General Public License 222 along with this program. If not, see <http://www.gnu.org/licenses/>.