├── CODE_OF_CONDUCT.md ├── CONTRIBUTING.md ├── LICENSE.txt ├── PLUGINS.md ├── README.md └── static ├── images ├── badge-awesome.svg ├── content-adm-3a-layout.jpg ├── content-block_insert.gif ├── content-homerow.png └── logo-vim-galore.png └── minimal-vimrc.vim /CODE_OF_CONDUCT.md: -------------------------------------------------------------------------------- 1 | # Contributor Covenant Code of Conduct 2 | 3 | ## Our Pledge 4 | 5 | We as members, contributors, and leaders pledge to make participation in our 6 | community a harassment-free experience for everyone, regardless of age, body 7 | size, visible or invisible disability, ethnicity, sex characteristics, gender 8 | identity and expression, level of experience, education, socio-economic status, 9 | nationality, personal appearance, race, caste, color, religion, or sexual identity 10 | and orientation. 11 | 12 | We pledge to act and interact in ways that contribute to an open, welcoming, 13 | diverse, inclusive, and healthy community. 14 | 15 | ## Our Standards 16 | 17 | Examples of behavior that contributes to a positive environment for our 18 | community include: 19 | 20 | * Demonstrating empathy and kindness toward other people 21 | * Being respectful of differing opinions, viewpoints, and experiences 22 | * Giving and gracefully accepting constructive feedback 23 | * Accepting responsibility and apologizing to those affected by our mistakes, 24 | and learning from the experience 25 | * Focusing on what is best not just for us as individuals, but for the 26 | overall community 27 | 28 | Examples of unacceptable behavior include: 29 | 30 | * The use of sexualized language or imagery, and sexual attention or 31 | advances of any kind 32 | * Trolling, insulting or derogatory comments, and personal or political attacks 33 | * Public or private harassment 34 | * Publishing others' private information, such as a physical or email 35 | address, without their explicit permission 36 | * Other conduct which could reasonably be considered inappropriate in a 37 | professional setting 38 | 39 | ## Enforcement Responsibilities 40 | 41 | Community leaders are responsible for clarifying and enforcing our standards of 42 | acceptable behavior and will take appropriate and fair corrective action in 43 | response to any behavior that they deem inappropriate, threatening, offensive, 44 | or harmful. 45 | 46 | Community leaders have the right and responsibility to remove, edit, or reject 47 | comments, commits, code, wiki edits, issues, and other contributions that are 48 | not aligned to this Code of Conduct, and will communicate reasons for moderation 49 | decisions when appropriate. 50 | 51 | ## Scope 52 | 53 | This Code of Conduct applies within all community spaces, and also applies when 54 | an individual is officially representing the community in public spaces. 55 | Examples of representing our community include using an official e-mail address, 56 | posting via an official social media account, or acting as an appointed 57 | representative at an online or offline event. 58 | 59 | ## Enforcement 60 | 61 | Instances of abusive, harassing, or otherwise unacceptable behavior may be 62 | reported to the community leaders responsible for enforcement at 63 | [INSERT CONTACT METHOD]. 64 | All complaints will be reviewed and investigated promptly and fairly. 65 | 66 | All community leaders are obligated to respect the privacy and security of the 67 | reporter of any incident. 68 | 69 | ## Enforcement Guidelines 70 | 71 | Community leaders will follow these Community Impact Guidelines in determining 72 | the consequences for any action they deem in violation of this Code of Conduct: 73 | 74 | ### 1. Correction 75 | 76 | **Community Impact**: Use of inappropriate language or other behavior deemed 77 | unprofessional or unwelcome in the community. 78 | 79 | **Consequence**: A private, written warning from community leaders, providing 80 | clarity around the nature of the violation and an explanation of why the 81 | behavior was inappropriate. A public apology may be requested. 82 | 83 | ### 2. Warning 84 | 85 | **Community Impact**: A violation through a single incident or series 86 | of actions. 87 | 88 | **Consequence**: A warning with consequences for continued behavior. No 89 | interaction with the people involved, including unsolicited interaction with 90 | those enforcing the Code of Conduct, for a specified period of time. This 91 | includes avoiding interactions in community spaces as well as external channels 92 | like social media. Violating these terms may lead to a temporary or 93 | permanent ban. 94 | 95 | ### 3. Temporary Ban 96 | 97 | **Community Impact**: A serious violation of community standards, including 98 | sustained inappropriate behavior. 99 | 100 | **Consequence**: A temporary ban from any sort of interaction or public 101 | communication with the community for a specified period of time. No public or 102 | private interaction with the people involved, including unsolicited interaction 103 | with those enforcing the Code of Conduct, is allowed during this period. 104 | Violating these terms may lead to a permanent ban. 105 | 106 | ### 4. Permanent Ban 107 | 108 | **Community Impact**: Demonstrating a pattern of violation of community 109 | standards, including sustained inappropriate behavior, harassment of an 110 | individual, or aggression toward or disparagement of classes of individuals. 111 | 112 | **Consequence**: A permanent ban from any sort of public interaction within 113 | the community. 114 | 115 | ## Attribution 116 | 117 | This Code of Conduct is adapted from the [Contributor Covenant][homepage], 118 | version 2.0, available at 119 | [https://www.contributor-covenant.org/version/2/0/code_of_conduct.html][v2.0]. 120 | 121 | Community Impact Guidelines were inspired by 122 | [Mozilla's code of conduct enforcement ladder][Mozilla CoC]. 123 | 124 | For answers to common questions about this code of conduct, see the FAQ at 125 | [https://www.contributor-covenant.org/faq][FAQ]. Translations are available 126 | at [https://www.contributor-covenant.org/translations][translations]. 127 | 128 | [homepage]: https://www.contributor-covenant.org 129 | [v2.0]: https://www.contributor-covenant.org/version/2/0/code_of_conduct.html 130 | [Mozilla CoC]: https://github.com/mozilla/diversity 131 | [FAQ]: https://www.contributor-covenant.org/faq 132 | [translations]: https://www.contributor-covenant.org/translations 133 | -------------------------------------------------------------------------------- /CONTRIBUTING.md: -------------------------------------------------------------------------------- 1 | # Contributing 2 | 3 | All kinds of contributions are welcome! 4 | 5 | - Wrong documentation? Technical mistakes happen all the time. Behaviour can 6 | change between different Vim versions. 7 | - Is there something you didn't understand right away? Was the explanation too 8 | complicated? 9 | - Any other suggestions for improvement? Better wording? Typos? Dead links? 10 | - Want to add plugins? Please make sure that they have collected a few stars 11 | already. There are new plugins every day and I can't possibly test them all, 12 | so I rely on "social proof" as an indicator for usefulness. (If you wrote or 13 | found a plugin with no or only very few stars but still think it's useful, 14 | promote it on [r/vim](https://www.reddit.com/r/vim). It has lots of readers 15 | and is great for gaining attention.) 16 | 17 | Please report _anything_ that seems wrong to you by 18 | [creating an issue](https://github.com/mhinz/vim-galore/issues/new) for it. 19 | 20 | If you feel like fixing it yourself, open a 21 | [pull request](https://help.github.com/categories/collaborating-with-issues-and-pull-requests). 22 | Don't worry too much about how to format your commit messages, the actual patch 23 | is more important. 24 | 25 | Thank you for contributing! 🎉 26 | -------------------------------------------------------------------------------- /LICENSE.txt: -------------------------------------------------------------------------------- 1 | Attribution-ShareAlike 4.0 International 2 | 3 | ======================================================================= 4 | 5 | Creative Commons Corporation ("Creative Commons") is not a law firm and 6 | does not provide legal services or legal advice. Distribution of 7 | Creative Commons public licenses does not create a lawyer-client or 8 | other relationship. Creative Commons makes its licenses and related 9 | information available on an "as-is" basis. Creative Commons gives no 10 | warranties regarding its licenses, any material licensed under their 11 | terms and conditions, or any related information. Creative Commons 12 | disclaims all liability for damages resulting from their use to the 13 | fullest extent possible. 14 | 15 | Using Creative Commons Public Licenses 16 | 17 | Creative Commons public licenses provide a standard set of terms and 18 | conditions that creators and other rights holders may use to share 19 | original works of authorship and other material subject to copyright 20 | and certain other rights specified in the public license below. The 21 | following considerations are for informational purposes only, are not 22 | exhaustive, and do not form part of our licenses. 23 | 24 | Considerations for licensors: Our public licenses are 25 | intended for use by those authorized to give the public 26 | permission to use material in ways otherwise restricted by 27 | copyright and certain other rights. Our licenses are 28 | irrevocable. Licensors should read and understand the terms 29 | and conditions of the license they choose before applying it. 30 | Licensors should also secure all rights necessary before 31 | applying our licenses so that the public can reuse the 32 | material as expected. Licensors should clearly mark any 33 | material not subject to the license. This includes other CC- 34 | licensed material, or material used under an exception or 35 | limitation to copyright. More considerations for licensors: 36 | wiki.creativecommons.org/Considerations_for_licensors 37 | 38 | Considerations for the public: By using one of our public 39 | licenses, a licensor grants the public permission to use the 40 | licensed material under specified terms and conditions. If 41 | the licensor's permission is not necessary for any reason--for 42 | example, because of any applicable exception or limitation to 43 | copyright--then that use is not regulated by the license. Our 44 | licenses grant only permissions under copyright and certain 45 | other rights that a licensor has authority to grant. Use of 46 | the licensed material may still be restricted for other 47 | reasons, including because others have copyright or other 48 | rights in the material. A licensor may make special requests, 49 | such as asking that all changes be marked or described. 50 | Although not required by our licenses, you are encouraged to 51 | respect those requests where reasonable. More_considerations 52 | for the public: 53 | wiki.creativecommons.org/Considerations_for_licensees 54 | 55 | ======================================================================= 56 | 57 | Creative Commons Attribution-ShareAlike 4.0 International Public 58 | License 59 | 60 | By exercising the Licensed Rights (defined below), You accept and agree 61 | to be bound by the terms and conditions of this Creative Commons 62 | Attribution-ShareAlike 4.0 International Public License ("Public 63 | License"). To the extent this Public License may be interpreted as a 64 | contract, You are granted the Licensed Rights in consideration of Your 65 | acceptance of these terms and conditions, and the Licensor grants You 66 | such rights in consideration of benefits the Licensor receives from 67 | making the Licensed Material available under these terms and 68 | conditions. 69 | 70 | 71 | Section 1 -- Definitions. 72 | 73 | a. Adapted Material means material subject to Copyright and Similar 74 | Rights that is derived from or based upon the Licensed Material 75 | and in which the Licensed Material is translated, altered, 76 | arranged, transformed, or otherwise modified in a manner requiring 77 | permission under the Copyright and Similar Rights held by the 78 | Licensor. For purposes of this Public License, where the Licensed 79 | Material is a musical work, performance, or sound recording, 80 | Adapted Material is always produced where the Licensed Material is 81 | synched in timed relation with a moving image. 82 | 83 | b. Adapter's License means the license You apply to Your Copyright 84 | and Similar Rights in Your contributions to Adapted Material in 85 | accordance with the terms and conditions of this Public License. 86 | 87 | c. BY-SA Compatible License means a license listed at 88 | creativecommons.org/compatiblelicenses, approved by Creative 89 | Commons as essentially the equivalent of this Public License. 90 | 91 | d. Copyright and Similar Rights means copyright and/or similar rights 92 | closely related to copyright including, without limitation, 93 | performance, broadcast, sound recording, and Sui Generis Database 94 | Rights, without regard to how the rights are labeled or 95 | categorized. For purposes of this Public License, the rights 96 | specified in Section 2(b)(1)-(2) are not Copyright and Similar 97 | Rights. 98 | 99 | e. Effective Technological Measures means those measures that, in the 100 | absence of proper authority, may not be circumvented under laws 101 | fulfilling obligations under Article 11 of the WIPO Copyright 102 | Treaty adopted on December 20, 1996, and/or similar international 103 | agreements. 104 | 105 | f. Exceptions and Limitations means fair use, fair dealing, and/or 106 | any other exception or limitation to Copyright and Similar Rights 107 | that applies to Your use of the Licensed Material. 108 | 109 | g. License Elements means the license attributes listed in the name 110 | of a Creative Commons Public License. The License Elements of this 111 | Public License are Attribution and ShareAlike. 112 | 113 | h. Licensed Material means the artistic or literary work, database, 114 | or other material to which the Licensor applied this Public 115 | License. 116 | 117 | i. Licensed Rights means the rights granted to You subject to the 118 | terms and conditions of this Public License, which are limited to 119 | all Copyright and Similar Rights that apply to Your use of the 120 | Licensed Material and that the Licensor has authority to license. 121 | 122 | j. Licensor means the individual(s) or entity(ies) granting rights 123 | under this Public License. 124 | 125 | k. Share means to provide material to the public by any means or 126 | process that requires permission under the Licensed Rights, such 127 | as reproduction, public display, public performance, distribution, 128 | dissemination, communication, or importation, and to make material 129 | available to the public including in ways that members of the 130 | public may access the material from a place and at a time 131 | individually chosen by them. 132 | 133 | l. Sui Generis Database Rights means rights other than copyright 134 | resulting from Directive 96/9/EC of the European Parliament and of 135 | the Council of 11 March 1996 on the legal protection of databases, 136 | as amended and/or succeeded, as well as other essentially 137 | equivalent rights anywhere in the world. 138 | 139 | m. You means the individual or entity exercising the Licensed Rights 140 | under this Public License. Your has a corresponding meaning. 141 | 142 | 143 | Section 2 -- Scope. 144 | 145 | a. License grant. 146 | 147 | 1. Subject to the terms and conditions of this Public License, 148 | the Licensor hereby grants You a worldwide, royalty-free, 149 | non-sublicensable, non-exclusive, irrevocable license to 150 | exercise the Licensed Rights in the Licensed Material to: 151 | 152 | a. reproduce and Share the Licensed Material, in whole or 153 | in part; and 154 | 155 | b. produce, reproduce, and Share Adapted Material. 156 | 157 | 2. Exceptions and Limitations. For the avoidance of doubt, where 158 | Exceptions and Limitations apply to Your use, this Public 159 | License does not apply, and You do not need to comply with 160 | its terms and conditions. 161 | 162 | 3. Term. The term of this Public License is specified in Section 163 | 6(a). 164 | 165 | 4. Media and formats; technical modifications allowed. The 166 | Licensor authorizes You to exercise the Licensed Rights in 167 | all media and formats whether now known or hereafter created, 168 | and to make technical modifications necessary to do so. The 169 | Licensor waives and/or agrees not to assert any right or 170 | authority to forbid You from making technical modifications 171 | necessary to exercise the Licensed Rights, including 172 | technical modifications necessary to circumvent Effective 173 | Technological Measures. For purposes of this Public License, 174 | simply making modifications authorized by this Section 2(a) 175 | (4) never produces Adapted Material. 176 | 177 | 5. Downstream recipients. 178 | 179 | a. Offer from the Licensor -- Licensed Material. Every 180 | recipient of the Licensed Material automatically 181 | receives an offer from the Licensor to exercise the 182 | Licensed Rights under the terms and conditions of this 183 | Public License. 184 | 185 | b. Additional offer from the Licensor -- Adapted Material. 186 | Every recipient of Adapted Material from You 187 | automatically receives an offer from the Licensor to 188 | exercise the Licensed Rights in the Adapted Material 189 | under the conditions of the Adapter's License You apply. 190 | 191 | c. No downstream restrictions. You may not offer or impose 192 | any additional or different terms or conditions on, or 193 | apply any Effective Technological Measures to, the 194 | Licensed Material if doing so restricts exercise of the 195 | Licensed Rights by any recipient of the Licensed 196 | Material. 197 | 198 | 6. No endorsement. Nothing in this Public License constitutes or 199 | may be construed as permission to assert or imply that You 200 | are, or that Your use of the Licensed Material is, connected 201 | with, or sponsored, endorsed, or granted official status by, 202 | the Licensor or others designated to receive attribution as 203 | provided in Section 3(a)(1)(A)(i). 204 | 205 | b. Other rights. 206 | 207 | 1. Moral rights, such as the right of integrity, are not 208 | licensed under this Public License, nor are publicity, 209 | privacy, and/or other similar personality rights; however, to 210 | the extent possible, the Licensor waives and/or agrees not to 211 | assert any such rights held by the Licensor to the limited 212 | extent necessary to allow You to exercise the Licensed 213 | Rights, but not otherwise. 214 | 215 | 2. Patent and trademark rights are not licensed under this 216 | Public License. 217 | 218 | 3. To the extent possible, the Licensor waives any right to 219 | collect royalties from You for the exercise of the Licensed 220 | Rights, whether directly or through a collecting society 221 | under any voluntary or waivable statutory or compulsory 222 | licensing scheme. In all other cases the Licensor expressly 223 | reserves any right to collect such royalties. 224 | 225 | 226 | Section 3 -- License Conditions. 227 | 228 | Your exercise of the Licensed Rights is expressly made subject to the 229 | following conditions. 230 | 231 | a. Attribution. 232 | 233 | 1. If You Share the Licensed Material (including in modified 234 | form), You must: 235 | 236 | a. retain the following if it is supplied by the Licensor 237 | with the Licensed Material: 238 | 239 | i. identification of the creator(s) of the Licensed 240 | Material and any others designated to receive 241 | attribution, in any reasonable manner requested by 242 | the Licensor (including by pseudonym if 243 | designated); 244 | 245 | ii. a copyright notice; 246 | 247 | iii. a notice that refers to this Public License; 248 | 249 | iv. a notice that refers to the disclaimer of 250 | warranties; 251 | 252 | v. a URI or hyperlink to the Licensed Material to the 253 | extent reasonably practicable; 254 | 255 | b. indicate if You modified the Licensed Material and 256 | retain an indication of any previous modifications; and 257 | 258 | c. indicate the Licensed Material is licensed under this 259 | Public License, and include the text of, or the URI or 260 | hyperlink to, this Public License. 261 | 262 | 2. You may satisfy the conditions in Section 3(a)(1) in any 263 | reasonable manner based on the medium, means, and context in 264 | which You Share the Licensed Material. For example, it may be 265 | reasonable to satisfy the conditions by providing a URI or 266 | hyperlink to a resource that includes the required 267 | information. 268 | 269 | 3. If requested by the Licensor, You must remove any of the 270 | information required by Section 3(a)(1)(A) to the extent 271 | reasonably practicable. 272 | 273 | b. ShareAlike. 274 | 275 | In addition to the conditions in Section 3(a), if You Share 276 | Adapted Material You produce, the following conditions also apply. 277 | 278 | 1. The Adapter's License You apply must be a Creative Commons 279 | license with the same License Elements, this version or 280 | later, or a BY-SA Compatible License. 281 | 282 | 2. You must include the text of, or the URI or hyperlink to, the 283 | Adapter's License You apply. You may satisfy this condition 284 | in any reasonable manner based on the medium, means, and 285 | context in which You Share Adapted Material. 286 | 287 | 3. You may not offer or impose any additional or different terms 288 | or conditions on, or apply any Effective Technological 289 | Measures to, Adapted Material that restrict exercise of the 290 | rights granted under the Adapter's License You apply. 291 | 292 | 293 | Section 4 -- Sui Generis Database Rights. 294 | 295 | Where the Licensed Rights include Sui Generis Database Rights that 296 | apply to Your use of the Licensed Material: 297 | 298 | a. for the avoidance of doubt, Section 2(a)(1) grants You the right 299 | to extract, reuse, reproduce, and Share all or a substantial 300 | portion of the contents of the database; 301 | 302 | b. if You include all or a substantial portion of the database 303 | contents in a database in which You have Sui Generis Database 304 | Rights, then the database in which You have Sui Generis Database 305 | Rights (but not its individual contents) is Adapted Material, 306 | 307 | including for purposes of Section 3(b); and 308 | c. You must comply with the conditions in Section 3(a) if You Share 309 | all or a substantial portion of the contents of the database. 310 | 311 | For the avoidance of doubt, this Section 4 supplements and does not 312 | replace Your obligations under this Public License where the Licensed 313 | Rights include other Copyright and Similar Rights. 314 | 315 | 316 | Section 5 -- Disclaimer of Warranties and Limitation of Liability. 317 | 318 | a. UNLESS OTHERWISE SEPARATELY UNDERTAKEN BY THE LICENSOR, TO THE 319 | EXTENT POSSIBLE, THE LICENSOR OFFERS THE LICENSED MATERIAL AS-IS 320 | AND AS-AVAILABLE, AND MAKES NO REPRESENTATIONS OR WARRANTIES OF 321 | ANY KIND CONCERNING THE LICENSED MATERIAL, WHETHER EXPRESS, 322 | IMPLIED, STATUTORY, OR OTHER. THIS INCLUDES, WITHOUT LIMITATION, 323 | WARRANTIES OF TITLE, MERCHANTABILITY, FITNESS FOR A PARTICULAR 324 | PURPOSE, NON-INFRINGEMENT, ABSENCE OF LATENT OR OTHER DEFECTS, 325 | ACCURACY, OR THE PRESENCE OR ABSENCE OF ERRORS, WHETHER OR NOT 326 | KNOWN OR DISCOVERABLE. WHERE DISCLAIMERS OF WARRANTIES ARE NOT 327 | ALLOWED IN FULL OR IN PART, THIS DISCLAIMER MAY NOT APPLY TO YOU. 328 | 329 | b. TO THE EXTENT POSSIBLE, IN NO EVENT WILL THE LICENSOR BE LIABLE 330 | TO YOU ON ANY LEGAL THEORY (INCLUDING, WITHOUT LIMITATION, 331 | NEGLIGENCE) OR OTHERWISE FOR ANY DIRECT, SPECIAL, INDIRECT, 332 | INCIDENTAL, CONSEQUENTIAL, PUNITIVE, EXEMPLARY, OR OTHER LOSSES, 333 | COSTS, EXPENSES, OR DAMAGES ARISING OUT OF THIS PUBLIC LICENSE OR 334 | USE OF THE LICENSED MATERIAL, EVEN IF THE LICENSOR HAS BEEN 335 | ADVISED OF THE POSSIBILITY OF SUCH LOSSES, COSTS, EXPENSES, OR 336 | DAMAGES. WHERE A LIMITATION OF LIABILITY IS NOT ALLOWED IN FULL OR 337 | IN PART, THIS LIMITATION MAY NOT APPLY TO YOU. 338 | 339 | c. The disclaimer of warranties and limitation of liability provided 340 | above shall be interpreted in a manner that, to the extent 341 | possible, most closely approximates an absolute disclaimer and 342 | waiver of all liability. 343 | 344 | 345 | Section 6 -- Term and Termination. 346 | 347 | a. This Public License applies for the term of the Copyright and 348 | Similar Rights licensed here. However, if You fail to comply with 349 | this Public License, then Your rights under this Public License 350 | terminate automatically. 351 | 352 | b. Where Your right to use the Licensed Material has terminated under 353 | Section 6(a), it reinstates: 354 | 355 | 1. automatically as of the date the violation is cured, provided 356 | it is cured within 30 days of Your discovery of the 357 | violation; or 358 | 359 | 2. upon express reinstatement by the Licensor. 360 | 361 | For the avoidance of doubt, this Section 6(b) does not affect any 362 | right the Licensor may have to seek remedies for Your violations 363 | of this Public License. 364 | 365 | c. For the avoidance of doubt, the Licensor may also offer the 366 | Licensed Material under separate terms or conditions or stop 367 | distributing the Licensed Material at any time; however, doing so 368 | will not terminate this Public License. 369 | 370 | d. Sections 1, 5, 6, 7, and 8 survive termination of this Public 371 | License. 372 | 373 | 374 | Section 7 -- Other Terms and Conditions. 375 | 376 | a. The Licensor shall not be bound by any additional or different 377 | terms or conditions communicated by You unless expressly agreed. 378 | 379 | b. Any arrangements, understandings, or agreements regarding the 380 | Licensed Material not stated herein are separate from and 381 | independent of the terms and conditions of this Public License. 382 | 383 | 384 | Section 8 -- Interpretation. 385 | 386 | a. For the avoidance of doubt, this Public License does not, and 387 | shall not be interpreted to, reduce, limit, restrict, or impose 388 | conditions on any use of the Licensed Material that could lawfully 389 | be made without permission under this Public License. 390 | 391 | b. To the extent possible, if any provision of this Public License is 392 | deemed unenforceable, it shall be automatically reformed to the 393 | minimum extent necessary to make it enforceable. If the provision 394 | cannot be reformed, it shall be severed from this Public License 395 | without affecting the enforceability of the remaining terms and 396 | conditions. 397 | 398 | c. No term or condition of this Public License will be waived and no 399 | failure to comply consented to unless expressly agreed to by the 400 | Licensor. 401 | 402 | d. Nothing in this Public License constitutes or may be interpreted 403 | as a limitation upon, or waiver of, any privileges and immunities 404 | that apply to the Licensor or You, including from the legal 405 | processes of any jurisdiction or authority. 406 | 407 | 408 | ======================================================================= 409 | 410 | Creative Commons is not a party to its public 411 | licenses. Notwithstanding, Creative Commons may elect to apply one of 412 | its public licenses to material it publishes and in those instances 413 | will be considered the “Licensor.” The text of the Creative Commons 414 | public licenses is dedicated to the public domain under the CC0 Public 415 | Domain Dedication. Except for the limited purpose of indicating that 416 | material is shared under a Creative Commons public license or as 417 | otherwise permitted by the Creative Commons policies published at 418 | creativecommons.org/policies, Creative Commons does not authorize the 419 | use of the trademark "Creative Commons" or any other trademark or logo 420 | of Creative Commons without its prior written consent including, 421 | without limitation, in connection with any unauthorized modifications 422 | to any of its public licenses or any other arrangements, 423 | understandings, or agreements concerning use of licensed material. For 424 | the avoidance of doubt, this paragraph does not form part of the 425 | public licenses. 426 | 427 | Creative Commons may be contacted at creativecommons.org. 428 | 429 | -------------------------------------------------------------------------------- /PLUGINS.md: -------------------------------------------------------------------------------- 1 | ## List of plugins 2 | 3 | #### [Colorschemes](#colorschemes-1) 4 | 5 | #### [By topic](#by-topic-1) 6 | 7 | - [Alignment](#alignment) 8 | - [Building and linting](#building-and-linting) 9 | - [Code completion](#code-completion) 10 | - [Commenters](#commenters) 11 | - [Cycle](#cycle) 12 | - [Databases](#databases) 13 | - [Delimiter](#delimiter) 14 | - [Fuzzy finders](#fuzzy-finders) 15 | - [Grep tools](#grep-tools) 16 | - [Indent](#indent) 17 | - [LSP](#lsp) 18 | - [Misc](#misc) 19 | - [Navigation](#navigation) 20 | - [Plugin managers](#plugin-managers) 21 | - [Snippets](#snippets) 22 | - [Statusline](#statusline) 23 | - [Surround](#surround) 24 | - [Taking notes](#taking-notes) 25 | - [Testing](#testing) 26 | - [Text objects](#text-objects) 27 | - [Tmux](#tmux) 28 | - [Undo history](#undo-history) 29 | - [Version control](#version-control) 30 | - [Writing](#writing) 31 | 32 | #### [By filetype](#by-filetype-1) 33 | 34 | - [C and C++](#c-and-c) 35 | - [Clojure](#clojure) 36 | - [Elixir](#elixir) 37 | - [Go](#go) 38 | - [HTML](#html) 39 | - [Java](#java) 40 | - [Javascript](#javascript) 41 | - [Lua](#lua) 42 | - [PHP](#php) 43 | - [Python](#python) 44 | - [Rust](#rust) 45 | - [TeX](#tex) 46 | - [VimL](#viml) 47 | 48 | ## Colorschemes 49 | 50 | Here's a list of commonly used colorschemes: 51 | 52 | - [acme-colors](https://github.com/plan9-for-vimspace/acme-colors) 53 | - [apprentice](https://github.com/romainl/Apprentice) 54 | - [base16](https://github.com/chriskempson/base16-vim) 55 | - [dracula](https://github.com/dracula/vim) 56 | - [gotham](https://github.com/whatyouhide/vim-gotham) 57 | - [gruvbox](https://github.com/morhetz/gruvbox) 58 | - [janah](https://github.com/mhinz/vim-janah) 59 | - [jellybeans](https://github.com/nanotech/jellybeans.vim) 60 | - [lucius](https://github.com/jonathanfilip/vim-lucius) 61 | - [molokai](https://github.com/tomasr/molokai) 62 | - [nofrils](https://github.com/robertmeta/nofrils) 63 | - [nord](https://github.com/arcticicestudio/nord-vim) 64 | - [oceanic-next](https://github.com/mhartington/oceanic-next) 65 | - [oceanic-next](https://github.com/mhartington/oceanic-next) 66 | - [onedark](https://github.com/joshdick/onedark.vim) 67 | - [paramount](https://github.com/owickstrom/vim-colors-paramount) 68 | - [railscasts](https://github.com/jpo/vim-railscasts-theme) 69 | - [seoul256](https://github.com/junegunn/seoul256.vim) 70 | - [solarized](https://github.com/altercation/vim-colors-solarized) (or [solarized8](https://github.com/lifepillar/vim-solarized8) or [flattened](https://github.com/romainl/flattened)) 71 | - [tomorrow](https://github.com/chriskempson/vim-tomorrow-theme) 72 | - [vividchalk](https://github.com/tpope/vim-vividchalk) 73 | - [yowish](https://github.com/kabbamine/yowish.vim) 74 | - [zenburn](https://github.com/jnurmine/Zenburn) 75 | 76 | Alternatively, generate your own colorscheme using [themer](https://github.com/mjswensen/themer) 77 | or [Colortemplate](https://github.com/lifepillar/vim-colortemplate). 78 | 79 | ## By topic 80 | 81 | #### Alignment 82 | 83 | - [tabular](https://github.com/godlygeek/tabular) 84 | - [vim-easy-align](https://github.com/junegunn/vim-easy-align) 85 | - [vim-lion](https://github.com/tommcdo/vim-lion) 86 | 87 | #### Building and linting 88 | 89 | - [ale](https://github.com/w0rp/ale) 90 | - [neomake](https://github.com/neomake/neomake) 91 | - [syntastic](https://github.com/vim-syntastic/syntastic) 92 | 93 | #### Code completion 94 | 95 | - [asyncomplete.vim](https://github.com/prabirshrestha/asyncomplete.vim) 96 | - [completor.vim](https://github.com/maralla/completor.vim) 97 | - [deoplete.nvim](https://github.com/Shougo/deoplete.nvim) 98 | - [neocomplete.vim](https://github.com/Shougo/neocomplete.vim) 99 | - [nvim-completion-manager](https://github.com/roxma/nvim-completion-manager) 100 | - [supertab](https://github.com/ervandew/supertab) 101 | - [vim-mucomplete](https://github.com/lifepillar/vim-mucomplete) 102 | - [VimCompletesMe](https://github.com/ajh17/VimCompletesMe) 103 | - [YouCompleteMe](https://github.com/Valloric/YouCompleteMe) 104 | 105 | #### Cycle 106 | 107 | - [switch.vim](https://github.com/AndrewRadev/switch.vim) 108 | - [vim-speeddating](https://github.com/tpope/vim-speeddating) 109 | 110 | #### Commenters 111 | 112 | - [nerdcommenter](https://github.com/scrooloose/nerdcommenter) 113 | - [tcomment_vim](https://github.com/tomtom/tcomment_vim) 114 | - [vim-commentary](https://github.com/tpope/vim-commentary) 115 | 116 | #### Databases 117 | 118 | - [pgsql.vim](https://github.com/lifepillar/pgsql.vim) 119 | - [vim-dadbod](https://github.com/tpope/vim-dadbod) 120 | 121 | #### Delimiter 122 | 123 | - [auto-pairs](https://github.com/jiangmiao/auto-pairs) 124 | - [delimitMate](https://github.com/Raimondi/delimitMate) 125 | - [vim-endwise](https://github.com/tpope/vim-endwise) 126 | 127 | #### Fuzzy finders 128 | 129 | - [Command-T](https://github.com/wincent/Command-T) (_requires +ruby_) 130 | - [ctrlp.vim](https://github.com/ctrlpvim/ctrlp.vim) 131 | - [denite.nvim](https://github.com/Shougo/denite.nvim) (_requires +python3_) 132 | - [fzf](https://github.com/junegunn/fzf) (and [fzf.vim](https://github.com/junegunn/fzf.vim)) 133 | - [LeaderF](https://github.com/Yggdroot/LeaderF) (_requires +python or +python3_) 134 | - [unite.vim](https://github.com/Shougo/unite.vim) 135 | 136 | #### Grep tools 137 | 138 | - [ctrlsf.vim](https://github.com/dyng/ctrlsf.vim) 139 | - [ferret](https://github.com/wincent/ferret) 140 | - [vim-grepper](https://github.com/mhinz/vim-grepper) 141 | 142 | #### Indent 143 | 144 | - [indentLine](https://github.com/Yggdroot/indentLine) 145 | - [vim-indent-guides](https://github.com/nathanaelkane/vim-indent-guides) 146 | 147 | #### LSP 148 | 149 | Plugins for the [Language Server Protocol](https://microsoft.github.io/language-server-protocol) 150 | 151 | - [coc.nvim](https://github.com/neoclide/coc.nvim) 152 | - [languageclient-neovim](https://github.com/autozimu/LanguageClient-neovim) 153 | - [vim-lsc](https://github.com/natebosch/vim-lsc) 154 | - [vim-lsp](https://github.com/prabirshrestha/vim-lsp) 155 | 156 | #### Navigation 157 | 158 | - [nerdtree](https://github.com/scrooloose/nerdtree) 159 | - [tagbar](https://github.com/majutsushi/tagbar) 160 | - [vim-dirvish](https://github.com/justinmk/vim-dirvish) 161 | - [vim-easymotion](https://github.com/easymotion/vim-easymotion) 162 | - [vim-sneak](https://github.com/justinmk/vim-sneak) 163 | - [vim-vinegar](https://github.com/tpope/vim-vinegar) 164 | - [vimfiler.vim](https://github.com/Shougo/vimfiler.vim) (_depends on other plugins_) 165 | 166 | Also see [fuzzy finders](#fuzzy-finders). 167 | 168 | #### Plugin managers 169 | 170 | - [apt-vim](https://github.com/egalpin/apt-vim) 171 | - [dein.vim](https://github.com/Shougo/dein.vim) 172 | - [minpac](https://github.com/k-takata/minpac) 173 | - [vim-addon-manager](https://github.com/MarcWeber/vim-addon-manager) 174 | - [vim-pathogen](https://github.com/tpope/vim-pathogen) 175 | - [vim-plug](https://github.com/junegunn/vim-plug) 176 | - [vundle.vim](https://github.com/VundleVim/Vundle.vim) 177 | 178 | #### Snippets 179 | 180 | - [neosnippet.vim](https://github.com/Shougo/neosnippet.vim) (_depends on other plugins_) 181 | - [ultisnips](https://github.com/SirVer/ultisnips) 182 | - [vim-snipmate](https://github.com/garbas/vim-snipmate) (_depends on other plugins_) 183 | - [xptemplate](https://github.com/drmingdrmer/xptemplate) 184 | 185 | #### Statusline 186 | 187 | - [lightline.vim](https://github.com/itchyny/lightline.vim) 188 | - [powerline](https://github.com/powerline/powerline) 189 | - [vim-airline](https://github.com/vim-airline/vim-airline) 190 | - [vim-flagship](https://github.com/tpope/vim-flagship) 191 | 192 | #### Surround 193 | 194 | - [vim-operator-surround](https://github.com/rhysd/vim-operator-surround) 195 | - [vim-sandwich](https://github.com/machakann/vim-sandwich) 196 | - [vim-surround](https://github.com/tpope/vim-surround) 197 | 198 | #### Taking notes 199 | 200 | - [vim-dotoo](https://github.com/dhruvasagar/vim-dotoo) 201 | - [vim-journal](https://github.com/junegunn/vim-journal) 202 | - [vim-notes](https://github.com/xolox/vim-notes) 203 | - [vim-orgmode](https://github.com/jceb/vim-orgmode) 204 | - [vim-pad](https://github.com/fmoralesc/vim-pad) 205 | - [vimwiki](https://github.com/vimwiki/vimwiki) 206 | 207 | #### Testing 208 | 209 | - [vim-test](https://github.com/janko-m/vim-test) 210 | 211 | #### Text objects 212 | 213 | - [targets.vim](https://github.com/wellle/targets.vim) 214 | - [vim-exchange](https://github.com/tommcdo/vim-exchange) 215 | - [vim-indent-object](https://github.com/michaeljsmith/vim-indent-object) 216 | - [vim-matchup](https://github.com/andymass/vim-matchup) 217 | - [vim-textobj-user](https://github.com/kana/vim-textobj-user) 218 | 219 | #### Tmux 220 | 221 | - [tmux-complete.vim](https://github.com/wellle/tmux-complete.vim) 222 | - [vim-dispatch](https://github.com/tpope/vim-dispatch) 223 | - [vim-tmux-navigator](https://github.com/christoomey/vim-tmux-navigator) 224 | - [vitality.vim](https://github.com/sjl/vitality.vim) 225 | 226 | #### Undo history 227 | 228 | - [gundo.vim](https://github.com/sjl/gundo.vim) 229 | - [undotree](https://github.com/mbbill/undotree) 230 | 231 | #### Version control 232 | 233 | - [agit.vim](https://github.com/cohama/agit.vim) 234 | - [committia.vim](https://github.com/rhysd/committia.vim) 235 | - [gist-vim](https://github.com/mattn/gist-vim) 236 | - [github-issues.vim](https://github.com/jaxbot/github-issues.vim) 237 | - [gitv](https://github.com/gregsexton/gitv) 238 | - [gv.vim](https://github.com/junegunn/gv.vim) 239 | - [nerdtree-git-plugin](https://github.com/Xuyuanp/nerdtree-git-plugin) 240 | - [vim-auto-programming](https://github.com/haya14busa/vim-auto-programming) 241 | - [vim-fugitive](https://github.com/tpope/vim-fugitive) 242 | - [vim-gitgutter](https://github.com/airblade/vim-gitgutter) 243 | - [vim-github-dashboard](https://github.com/junegunn/vim-github-dashboard) 244 | - [vim-lawrencium](https://bitbucket.org/ludovicchabant/vim-lawrencium) 245 | - [vim-signify](https://github.com/mhinz/vim-signify) 246 | - [vim-twiggy](https://github.com/sodapopcan/vim-twiggy) 247 | - [vimagit](https://github.com/jreybert/vimagit) 248 | 249 | #### Writing 250 | 251 | - [thesaurus_query.vim](https://github.com/ron89/thesaurus_query.vim) 252 | - [vim-grammarous](https://github.com/rhysd/vim-grammarous) 253 | - [vim-LanguageTool](https://github.com/dpelle/vim-LanguageTool) 254 | - [vim-online-thesaurus](https://github.com/beloglazov/vim-online-thesaurus) 255 | - [vim-textobj-quote](https://github.com/reedes/vim-textobj-quote) 256 | - [vim-wordy](https://github.com/reedes/vim-wordy) 257 | 258 | #### Misc 259 | 260 | - [calendar.vim](https://github.com/itchyny/calendar.vim) 261 | - [CoVim](https://github.com/FredKSchott/CoVim) 262 | - [FastFold](https://github.com/Konfekt/FastFold) 263 | - [goyo.vim](https://github.com/junegunn/goyo.vim) 264 | - [is.vim](https://github.com/haya14busa/is.vim) 265 | - [limelight.vim](https://github.com/junegunn/limelight.vim) 266 | - [NrrwRgn](https://github.com/chrisbra/NrrwRgn) 267 | - [sideways.vim](https://github.com/AndrewRadev/sideways.vim) 268 | - [splitjoin.vim](https://github.com/AndrewRadev/splitjoin.vim) 269 | - [unicode.vim](https://github.com/chrisbra/unicode.vim) 270 | - [vim-abolish](https://github.com/tpope/vim-abolish) 271 | - [vim-bracketed-paste](https://github.com/ConradIrwin/vim-bracketed-paste) 272 | - [vim-devicons](https://github.com/ryanoasis/vim-devicons) 273 | - [vim-diff-enhanced](https://github.com/chrisbra/vim-diff-enhanced) 274 | - [vim-diminactive](https://github.com/blueyed/vim-diminactive) 275 | - [vim-fixkey](https://github.com/drmikehenry/vim-fixkey) 276 | - [vim-gnupg](https://github.com/jamessan/vim-gnupg) 277 | - [vim-gutentags](https://github.com/ludovicchabant/vim-gutentags) 278 | - [vim-hackernews](https://github.com/ryanss/vim-hackernews) 279 | - [vim-move](https://github.com/matze/vim-move) 280 | - [vim-multiple-cursors](https://github.com/terryma/vim-multiple-cursors) 281 | - [vim-projectionist](https://github.com/tpope/vim-projectionist) 282 | - [vim-qf](https://github.com/romainl/vim-qf) 283 | - [vim-rsi](https://github.com/tpope/vim-rsi) 284 | - [vim-sleuth](https://github.com/tpope/vim-sleuth) 285 | - [vim-startify](https://github.com/mhinz/vim-startify) 286 | - [vim-unimpaired](https://github.com/tpope/vim-unimpaired) 287 | 288 | ## By filetype 289 | 290 | #### C and C++ 291 | 292 | - [a.vim](https://github.com/vim-scripts/a.vim) 293 | - [clang_complete](https://github.com/Rip-Rip/clang_complete) 294 | - [color_coded](https://github.com/jeaye/color_coded) 295 | - [lh-cpp](https://github.com/LucHermitte/lh-cpp) 296 | - [vim-cpp-enhanced-highlight](https://github.com/octol/vim-cpp-enhanced-highlight) 297 | - [vim-rtags](https://github.com/lyuts/vim-rtags) 298 | 299 | #### Clojure 300 | 301 | - [paredit](https://github.com/kovisoft/paredit) 302 | - [rainbow_parentheses.vim](https://github.com/junegunn/rainbow_parentheses.vim) 303 | - [vim-clojure-highlight](https://github.com/guns/vim-clojure-highlight) 304 | - [vim-fireplace](https://github.com/tpope/vim-fireplace) 305 | - [vim-salve](https://github.com/tpope/vim-salve) 306 | - [vim-sexp-mappings-for-regular-people](https://github.com/tpope/vim-sexp-mappings-for-regular-people) 307 | - [vim-sexp](https://github.com/guns/vim-sexp) 308 | 309 | #### Elixir 310 | 311 | - [alchemist.vim](https://github.com/slashmili/alchemist.vim) 312 | - [vim-elixir](https://github.com/elixir-editors/vim-elixir) 313 | - [vim-mix-format](https://github.com/mhinz/vim-mix-format) 314 | 315 | #### Go 316 | 317 | - [gofmt.vim](https://github.com/tweekmonster/gofmt.vim) 318 | - [hl-goimport.vim](https://github.com/tweekmonster/hl-goimport.vim) 319 | - [vim-go](https://github.com/fatih/vim-go) 320 | - [vim-godebug](https://github.com/jodosha/vim-godebug) 321 | 322 | #### HTML 323 | 324 | - [emmet-vim](https://github.com/mattn/emmet-vim) 325 | - [html5.vim](https://github.com/othree/html5.vim) 326 | 327 | #### Java 328 | 329 | - [vim-javacomplete2](https://github.com/artur-shaik/vim-javacomplete2) 330 | 331 | #### Javascript 332 | 333 | - [es.next.syntax.vim](https://github.com/othree/es.next.syntax.vim) 334 | - [javascript-libraries-syntax.vim](https://github.com/othree/javascript-libraries-syntax.vim) 335 | - [node-vim-debugger](https://github.com/sidorares/node-vim-debugger) 336 | - [tern_for_vim](https://github.com/ternjs/tern_for_vim) 337 | - [vim-esformatter](https://github.com/millermedeiros/vim-esformatter) 338 | - [vim-flow](https://github.com/flowtype/vim-flow) 339 | - [vim-javascript-syntax](https://github.com/jelera/vim-javascript-syntax) 340 | - [vim-javascript](https://github.com/pangloss/vim-javascript) 341 | - [vim-jsx](https://github.com/mxw/vim-jsx) 342 | - [vim-node](https://github.com/moll/vim-node) 343 | - [vim-prettier](https://github.com/prettier/vim-prettier) 344 | - [yajs.vim](https://github.com/othree/yajs.vim) 345 | - [yats.vim](https://github.com/HerringtonDarkholme/yats.vim) 346 | 347 | #### Lua 348 | 349 | - [vim-lua-ftplugin](https://github.com/xolox/vim-lua-ftplugin) 350 | - [vim-lua-inspect](https://github.com/xolox/vim-lua-inspect) 351 | 352 | #### PHP 353 | 354 | - [php.vim](https://github.com/StanAngeloff/php.vim) 355 | - [vim-php-cs-fixer](https://github.com/stephpy/vim-php-cs-fixer) 356 | - [vim-php-namespace](https://github.com/arnaud-lb/vim-php-namespace) 357 | - [vim-php-refactoring-toolbox](https://github.com/adoy/vim-php-refactoring-toolbox) 358 | 359 | #### Python 360 | 361 | - [braceless.vim](https://github.com/tweekmonster/braceless.vim) 362 | - [impsort.vim](https://github.com/tweekmonster/impsort.vim) 363 | - [jedi-vim](https://github.com/davidhalter/jedi-vim) 364 | - [python-mode](https://github.com/klen/python-mode) 365 | - [SimpylFold](https://github.com/tmhedberg/SimpylFold) 366 | - [vim-flake8](https://github.com/nvie/vim-flake8) 367 | 368 | #### Rust 369 | 370 | - [rust.vim](https://github.com/rust-lang/rust.vim) 371 | - [vim-crates](https://github.com/mhinz/vim-crates) 372 | - [vim-racer](https://github.com/racer-rust/vim-racer) 373 | 374 | #### TeX 375 | 376 | - [vimtex](https://github.com/lervag/vimtex) 377 | 378 | #### VimL 379 | 380 | - [exception.vim](https://github.com/tweekmonster/exception.vim) 381 | - [helpful.vim](https://github.com/tweekmonster/helpful.vim) 382 | - [vader.vim](https://github.com/junegunn/vader.vim) 383 | - [vim-lookup](https://github.com/mhinz/vim-lookup) 384 | - [vim-scriptease](https://github.com/tpope/vim-scriptease) 385 | - [vim-themis](https://github.com/thinca/vim-themis) 386 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 |
2 |


3 | vim-galore logo 4 |



5 |
6 | Chinese | 7 | Japanese | 8 | Portuguese | 9 | Russian | 10 | Vietnamese 11 |
12 |
13 | Licensed under CC BY-SA 4.0. 14 |
15 |
16 |

17 |
18 | 19 | ### [Intro](#intro-1) 20 | 21 | - [What is Vim?](#what-is-vim) 22 | - [The Vim Philosophy](#the-vim-philosophy) 23 | - [First steps](#first-steps) 24 | - [Minimal vimrc](#minimal-vimrc) 25 | - [What kind of Vim am I running?](#what-kind-of-vim-am-i-running) 26 | - [Cheatsheets](#cheatsheets) 27 | 28 | ### [Basics](#basics-1) 29 | 30 | - [Buffers, windows, tabs](#buffers-windows-tabs) 31 | - [Active, loaded, listed, named buffers](#active-loaded-listed-named-buffers) 32 | - [Argument list](#argument-list) 33 | - [Mappings](#mappings) 34 | - [Mapleader](#mapleader) 35 | - [Registers](#registers) 36 | - [Ranges](#ranges) 37 | - [Marks](#marks) 38 | - [Completion](#completion) 39 | - [Motions, operators, text objects](#motions-operators-text-objects) 40 | - [Autocmds](#autocmds) 41 | - [Changelist, jumplist](#changelist-jumplist) 42 | - [Undo tree](#undo-tree) 43 | - [Quickfix and location lists](#quickfix-and-location-lists) 44 | - [Macros](#macros) 45 | - [Colorschemes](#colorschemes) 46 | - [Folding](#folding) 47 | - [Sessions](#sessions) 48 | - [Locality](#locality) 49 | 50 | ### [Usage](#usage-1) 51 | 52 | - [Getting help offline](#getting-help-offline) 53 | - [Getting help offline (alternative)](#getting-help-offline-alternative) 54 | - [Getting help online](#getting-help-online) 55 | - [Autocmds in practice](#autocmds-in-practice) 56 | - [User events](#user-events) 57 | - [Nested autocmds](#nested-autocmds) 58 | - [Clipboard](#clipboard) 59 | - [Clipboard usage (Windows, macOS)](#clipboard-usage-windows-macos) 60 | - [Clipboard usage (Linux, BSD, ...)](#clipboard-usage-linux-bsd-) 61 | - [Restore cursor position when opening file](#restore-cursor-position-when-opening-file) 62 | - [Temporary files](#temporary-files) 63 | - [Backup files](#backup-files) 64 | - [Swap files](#swap-files) 65 | - [Undo files](#undo-files) 66 | - [Viminfo files](#viminfo-files) 67 | - [Example configuration for temporary files](#example-configuration-for-temporary-files) 68 | - [Editing remote files](#editing-remote-files) 69 | - [Managing plugins](#managing-plugins) 70 | - [Block insert](#block-insert) 71 | - [Running external programs and using filters](#running-external-programs-and-using-filters) 72 | - [Cscope](#cscope) 73 | - [MatchIt](#matchit) 74 | - [True colors](#true-colors) 75 | 76 | ### [Tips](#tips-1) 77 | 78 | - [Go to other end of selected text](#go-to-other-end-of-selected-text) 79 | - [Saner behavior of n and N](#saner-behavior-of-n-and-n) 80 | - [Saner command-line history](#saner-command-line-history) 81 | - [Saner CTRL-L](#saner-ctrl-l) 82 | - [Disable audible and visual bells](#disable-audible-and-visual-bells) 83 | - [Quickly move current line](#quickly-move-current-line) 84 | - [Quickly add empty lines](#quickly-add-empty-lines) 85 | - [Quickly edit your macros](#quickly-edit-your-macros) 86 | - [Quickly jump to header or source file](#quickly-jump-to-header-or-source-file) 87 | - [Quickly change font size in GUI](#quickly-change-font-size-in-gui) 88 | - [Change cursor style dependent on mode](#change-cursor-style-dependent-on-mode) 89 | - [Don't lose selection when shifting sidewards](#dont-lose-selection-when-shifting-sidewards) 90 | - [Reload a file on saving](#reload-a-file-on-saving) 91 | - [Smarter cursorline](#smarter-cursorline) 92 | - [Faster keyword completion](#faster-keyword-completion) 93 | - [Cosmetic changes to colorschemes](#cosmetic-changes-to-colorschemes) 94 | 95 | ### [Commands](#commands-1) 96 | 97 | - [:global and :vglobal](#global-and-vglobal) - Execute a command on all matching lines. 98 | - [:normal and :execute](#normal-and-execute) - The scripting dream team. 99 | - [:redir and execute()](#redir-and-execute) - Capture command output. 100 | 101 | ### [Debugging](#debugging-1) 102 | 103 | - [General tips](#general-tips) 104 | - [Verbosity](#verbosity) 105 | - [Profiling startup time](#profiling-startup-time) 106 | - [Profiling at runtime](#profiling-at-runtime) 107 | - [Debugging Vim scripts](#debugging-vim-scripts) 108 | - [Debugging syntax files](#debugging-syntax-files) 109 | 110 | ### [Miscellaneous](#miscellaneous-1) 111 | 112 | - [Additional resources](#additional-resources) 113 | - [Vim distributions](#vim-distributions) 114 | - [Standard plugins](#standard-plugins) 115 | - [Map CapsLock to Control](#map-capslock-to-control) 116 | - [Generating HTML from buffer](#generating-html-from-buffer) 117 | - [Easter eggs](#easter-eggs) 118 | - [Why hjkl for navigation?](#why-hjkl-for-navigation) 119 | 120 | ### [Common problems](#common-problems-1) 121 | 122 | - [Editing small files is slow](#editing-small-files-is-slow) 123 | - [Editing huge files is slow](#editing-huge-files-is-slow) 124 | - [Bracketed paste (or why do I have to set 'paste' all the time?)](#bracketed-paste-or-why-do-i-have-to-set-paste-all-the-time) 125 | - [Delays when using escape key in terminal](#delays-when-using-escape-key-in-terminal) 126 | - [Function search undo](#function-search-undo) 127 | 128 | ### [Technical quirks](#technical-quirks-1) 129 | 130 | - [Newline used for NUL](#newline-used-for-nul) 131 | 132 | ### [Terminology](#terminology-1) 133 | 134 | - [Vim script? Vimscript? VimL?](#vim-script-vimscript-viml) 135 | 136 | ### [List of colorschemes](PLUGINS.md#colorschemes-1) 137 | 138 | ### [List of plugins](PLUGINS.md) 139 | 140 |
141 | 142 | # Intro 143 | 144 | ## What is Vim? 145 | 146 | [Vim](http://www.vim.org) is a text editor with a long line of ancestors that 147 | goes back to [qed](https://en.wikipedia.org/wiki/QED_(text_editor)). [Bram 148 | Moolenaar](https://en.wikipedia.org/wiki/Bram_Moolenaar) released it in 1991. 149 | 150 | The project is hosted online at [vim.org](http://www.vim.org/index.php). 151 | 152 | Getting Vim: Use your favourite package manager or visit the [download 153 | page](http://www.vim.org/download.php) from vim.org. 154 | 155 | Discussions and user questions are best done on the 156 | [vim_use](https://groups.google.com/forum/#!forum/vim_use) mailing list or using 157 | IRC ([Freenode](https://freenode.net)) in the `#vim` channel. 158 | 159 | Development happens on [GitHub](https://github.com/vim/vim), discussions on the 160 | [vim_dev](https://groups.google.com/forum/#!forum/vim_dev) mailing list. 161 | 162 | Read [Why, oh WHY, do those #?@! nutheads use 163 | vi?](http://www.viemu.com/a-why-vi-vim.html) to see common misconceptions about 164 | Vim explained. 165 | 166 | ## The Vim Philosophy 167 | 168 | Vim adheres to the modal editing philosophy. This means that it provides 169 | multiple modes and the meaning of keys changes according to the mode. You 170 | navigate files in _normal mode_, you insert text in _insert mode_, you select 171 | lines in _visual mode_, you access commands in _command-line mode_ and so on. 172 | This might sound complicated at first, but has a huge advantage: you don't have 173 | to break your fingers by holding several keys at once, most of the time you 174 | simply press them one after the other. The more common the task, the fewer keys 175 | are needed. 176 | 177 | A related concept that works well with modal editing are operators and motions. 178 | _Operators_ start a certain action, e.g. changing, removing, or selecting text. 179 | Afterwards you specify the region of text you want to act on using a _motion_. 180 | To change everything between parentheses, use `ci(` (read _change inner 181 | parentheses_). To remove an entire paragraph of text, use `dap` (read _delete 182 | around paragraph_). 183 | 184 | If you see advanced Vim users working, you'll notice that they speak the 185 | _language of Vim_ as well as pianists handle their instruments. Complex 186 | operations are done using only a few key presses. They don't even think about it 187 | anymore as [muscle memory](https://en.wikipedia.org/wiki/Muscle_memory) took 188 | over already. This reduces [cognitive 189 | load](https://en.wikipedia.org/wiki/Cognitive_load) and helps to focus on the 190 | actual task. 191 | 192 | ## First steps 193 | 194 | Vim comes bundled with an interactive tutorial that teaches the most basic 195 | things you need to know about. You can start it from the shell: 196 | 197 | ``` 198 | $ vimtutor 199 | ``` 200 | 201 | Don't be put off by how boring it looks like and work through the exercises. The 202 | editors or IDEs you used before were most probably all non-modal, so working by 203 | switching modes will seem awkward at first, but the more you use Vim, the more 204 | it becomes [muscle memory](https://en.wikipedia.org/wiki/Muscle_memory). 205 | 206 | Vim was bolted on [Stevie](https://en.wikipedia.org/wiki/Stevie_(text_editor)), a 207 | [vi](https://en.wikipedia.org/wiki/Vi) clone, and supports two operating modes: 208 | "compatible" and "nocompatible". Using Vim in compatible mode means using vi 209 | defaults for all options, opposed to Vim defaults. As long as you didn't create 210 | a user vimrc yet or started Vim with `vim -N`, compatible mode is assumed! Don't 211 | use Vim in compatible mode. Just don't. 212 | 213 | Next steps: 214 | 215 | 1. Create your own [vimrc](#minimal-vimrc). 216 | 2. Have some [cheatsheets](#cheatsheets) ready for the first weeks. 217 | 3. Read through the [basics](#basics-1) section to learn what is even possible. 218 | 4. Learn on demand! You never finish learning Vim. If you encounter any 219 | problems, just look for it on the internet. Your problem was solved already. 220 | Vim comes with great documentation and knowing how to navigate it is a must: 221 | [Getting help offline](#getting-help-offline). 222 | 5. Have a look at the [additional resources](#additional-resources). 223 | 224 | One last advice: Please learn how to use Vim properly before starting to add all 225 | kinds of hyped [plugins](#managing-plugins) that only implement features that 226 | Vim already supports natively. 227 | 228 | ## Minimal vimrc 229 | 230 | The user vimrc can be put into `~/.vimrc` or for the sake of better separation 231 | into `~/.vim/vimrc`. The latter makes it easy to put the entire configuration 232 | under version control and upload it to, let's say GitHub. 233 | 234 | You find many "minimal vimrcs" all over the net, and maybe my version isn't as 235 | minimal as it should be, but it provides a good set of sane settings that I deem 236 | to be useful for starting out. 237 | 238 | Eventually you have to read up on all the mentioned settings anyway and decide 239 | for yourself. :-) 240 | 241 | So here it is: [minimal-vimrc](static/minimal-vimrc.vim) 242 | 243 | In case you're interested, here's 244 | [my vimrc](https://github.com/mhinz/dotfiles/blob/master/.vim/vimrc). 245 | 246 | **TIP**: Most plugin authors maintain several plugins and also publish their 247 | vimrc on GitHub (often in a repository called "vim-config" or "dotfiles"), so 248 | whenever you find a plugin you like, look up its maintainer's GitHub page and 249 | look through the repositories. 250 | 251 | ## What kind of Vim am I running? 252 | 253 | Looking at `:version` will give you all the information you need to know about 254 | how the currently running Vim binary was compiled. 255 | 256 | The first line tells you when the binary was compiled and the version, e.g. 7.4. 257 | One of the next lines states `Included patches: 1-1051`, which is the patch 258 | level. Thus, your exact Vim version is 7.4.1051. 259 | 260 | Another line states something like `Tiny version without GUI` or `Huge version 261 | with GUI`. The obvious information from that is whether your Vim includes GUI 262 | support, e.g. for starting `gvim` from the shell or running `:gui` from Vim 263 | within a terminal emulator. The other important information is the `Tiny` and 264 | `Huge`. Vim distinguishes between feature sets called `tiny`, `small`, `normal`, 265 | `big`, and `huge`, all enabling different subsets of features. 266 | 267 | The majority of `:version` output is consumed by the feature list itself. 268 | `+clipboard` means the clipboard feature was compiled in, `-clipboard` means it 269 | wasn't compiled in. 270 | 271 | A few Vim features need to be compiled in for them to work. E.g. for `:prof` to 272 | work, you need a Vim with a huge feature set, because that set enables the 273 | `+profile` feature. 274 | 275 | If that's not the case and you installed Vim from a package manager, make sure 276 | to install a package called `vim-x`, `vim-x11`, `vim-gtk`, `vim-gnome` or 277 | similar, since these packages usually come with the huge feature set. 278 | 279 | You can also test for the version or features programmatically: 280 | 281 | ```vim 282 | " Do something if running at least Vim 7.4.42 with +profile enabled. 283 | if (v:version > 704 || v:version == 704 && has('patch42')) && has('profile') 284 | " do stuff 285 | endif 286 | ``` 287 | 288 | Help: 289 | 290 | ``` 291 | :h :version 292 | :h feature-list 293 | :h +feature-list 294 | :h has-patch 295 | ``` 296 | 297 | ## Cheatsheets 298 | 299 | - http://people.csail.mit.edu/vgod/vim/vim-cheat-sheet-en.png 300 | - https://cdn.shopify.com/s/files/1/0165/4168/files/preview.png 301 | - http://michael.peopleofhonoronly.com/vim/vim_cheat_sheet_for_programmers_screen.png 302 | - http://www.rosipov.com/images/posts/vim-movement-commands-cheatsheet.png 303 | 304 | Or quickly open a cheatsheet from within Vim: [vim-cheat40](https://github.com/lifepillar/vim-cheat40). 305 | 306 | # Basics 307 | 308 | ## Buffers, windows, tabs 309 | 310 | Vim is a text editor. Every time text is shown, the text is part of a 311 | **buffer**. Each file will be opened in its own buffer. Plugins show stuff in 312 | their own buffers etc. 313 | 314 | Buffers have many attributes, e.g. whether the text it contains is modifiable, 315 | or whether it is associated with a file and thus needs to be synchronized to 316 | disk on saving. 317 | 318 | **Windows** are viewports _onto_ buffers. If you want to view several files at 319 | the same time or even different locations of the same file, you use windows. 320 | 321 | And please, please don't call them _splits_. You can split a window in two, but 322 | that doesn't make them _splits_. 323 | 324 | Windows can be split vertically or horizontally and the heights and widths of 325 | existing windows can be altered, too. Therefore, you can use whatever window 326 | layout you prefer. 327 | 328 | A **tab page** (or just tab) is a collection of windows. Thus, if you want to 329 | use multiple window layouts, use tabs. 330 | 331 | Putting it in a nutshell, if you start Vim without arguments, you'll have one 332 | tab page that holds one window that shows one buffer. 333 | 334 | By the way, the buffer list is global and you can access any buffer from any 335 | tab. 336 | 337 | ## Active, loaded, listed, named buffers 338 | 339 | Run Vim like this `vim file1`. The file's content will be loaded into a buffer. 340 | You have a **loaded buffer** now. The content of the buffer is only synchronized 341 | to disk (written back to the file) if you save it within Vim. 342 | 343 | Since the buffer is also shown in a window, it's also an **active buffer**. Now 344 | if you load another file via `:e file2`, `file1` will become a **hidden buffer** 345 | and `file2` the active one. 346 | 347 | Both buffers are also **listed**, thus they will get listed in the output of 348 | `:ls`. Plugin buffers or help buffers are often marked as unlisted, since 349 | they're not regular files you usually edit with a text editor. Listed and 350 | unlisted buffers can be shown via `:ls!`. 351 | 352 | **Unnamed buffers**, also often used by plugins, are buffers that don't have an 353 | associated filename. E.g. `:enew` will create an unnamed scratch buffer. Add 354 | some text and write it to disk via `:w /tmp/foo`, and it will become a named 355 | buffer. 356 | 357 | ## Argument list 358 | 359 | The [global buffer list](#buffers-windows-tabs) is a Vim thing. Before that, in 360 | vi, there only used to be the argument list, which is also available in Vim. 361 | 362 | Every filename given to Vim on the shell command-line, is remembered in the 363 | argument list. There can be multiple argument lists: by default all arguments 364 | are put into the global argument list, but you can use `:arglocal` to create a 365 | new argument list that is local to the window. 366 | 367 | List the current arguments with `:args`. Switch between files from the argument 368 | list with `:next`, `:previous`, `:first`, `:last` and friends. Alter it with 369 | `:argadd`, `:argdelete` or `:args` with a list of files. 370 | 371 | If you should prefer using the buffer or argument list for working with files is 372 | a matter of taste. My impression is that most people use the buffer list 373 | exclusively. 374 | 375 | Nevertheless, there is one huge use case for the argument list: batch processing 376 | via `:argdo`! A simple refactoring example: 377 | 378 | ```vim 379 | :args **/*.[ch] 380 | :argdo %s/foo/bar/ge | update 381 | ``` 382 | 383 | This replaces all occurrences of "foo" by "bar" in all C source and header files 384 | from the current directory and below. 385 | 386 | Help: `:h argument-list` 387 | 388 | ## Mappings 389 | 390 | You can define your own mappings with the `:map` family of commands. Each 391 | command of that family defines a mapping for a certain set of modes. Technically 392 | Vim comes with a whopping 12 modes, 6 of them can be mapped. Additionally, some 393 | commands act on multiple modes at once. 394 | 395 | | Recursive | Non-recursive | Unmap | Modes | 396 | |-----------|---------------|-----------|----------------------------------| 397 | | `:map` | `:noremap` | `:unmap` | normal, visual, operator-pending | 398 | | `:nmap` | `:nnoremap` | `:nunmap` | normal | 399 | | `:xmap` | `:xnoremap` | `:xunmap` | visual | 400 | | `:cmap` | `:cnoremap` | `:cunmap` | command-line | 401 | | `:omap` | `:onoremap` | `:ounmap` | operator-pending | 402 | | `:imap` | `:inoremap` | `:iunmap` | insert | 403 | 404 | E.g. this defines the mapping for normal mode only: 405 | 406 | ```vim 407 | :nmap :echo "foo" 408 | ``` 409 | 410 | Unmap it again by using `:nunmap `. 411 | 412 | For a few more but rather uncommon modes (or combinations of them), see `:h 413 | map-modes`. 414 | 415 | So far, so good. There's only one problem that can be pretty confusing to 416 | beginners: `:nmap` is _recursive_! That is, the right-hand side takes other 417 | mappings into account. 418 | 419 | So you defined a mapping that simply echoes "Foo": 420 | 421 | ```vim 422 | :nmap b :echo "Foo" 423 | ``` 424 | 425 | But what if you want to map the default behavior of `b` (going one word back) to 426 | another key? 427 | 428 | ```vim 429 | :nmap a b 430 | ``` 431 | 432 | If you hit a, we expect the cursor to go back a word, but instead 433 | "Foo" is printed in the command-line! Because the right-hand side, `b`, was 434 | mapped to another action already, namely `:echo "Foo"`. 435 | 436 | The proper way to resolve this problem is to use a _non-recursive_ mapping 437 | instead: 438 | 439 | ```vim 440 | :nnoremap a b 441 | ``` 442 | 443 | Rule of thumb: Always use non-recursive mappings unless recursing is actually 444 | desired. 445 | 446 | Look up your mappings by not giving a right-hand side. E.g. `:nmap` shows all 447 | normal mappings and `:nmap ` shows all normal mappings that start with 448 | the mapleader. 449 | 450 | If you want to disable a standard mapping, map them to the special `` 451 | character, e.g. `:noremap `. 452 | 453 | Help: 454 | 455 | :h key-notation 456 | :h mapping 457 | :h 05.3 458 | 459 | ## Mapleader 460 | 461 | The mapleader is simply a placeholder than can be used with custom mappings and 462 | is set to `\` by default. 463 | 464 | ```vim 465 | nnoremap h :helpgrep 466 | ``` 467 | 468 | This mapping is triggered by `\h`. If you want to use `h` instead: 469 | 470 | ```vim 471 | let mapleader = ' ' 472 | nnoremap h :helpgrep 473 | ``` 474 | 475 | Moreover, there is `` that is the local counterpart to `` 476 | and is supposed to be used for mappings that are local to the buffer, eg. 477 | filetype-specific plugins. It also defaults to `\`. 478 | 479 | **Note**: Set the mapleaders before mappings! All leader mappings that are in 480 | effect already, won't change just because the mapleader was changed. `:nmap 481 | ` will show all normal mode leader mappings with the mapleader resolved 482 | already, so use it to double-check your mappings. 483 | 484 | See `:h mapleader` and `:h maplocalleader` for more. 485 | 486 | ## Registers 487 | 488 | Registers are slots that save text. Copying text into a register is called 489 | **yanking** and extracting text from a register is called **pasting**. 490 | 491 | Vim provides the following registers: 492 | 493 | | Type | Character | Filled by? | Readonly? | Contains text from? | 494 | |---------------------|------------------------|------------|-----------|---------------------| 495 | | Unnamed | `"` | vim | [ ] | Last yank or deletion. (`d`, `c`, `s`, `x`, `y`) | 496 | | Numbered | `0` to `9` | vim | [ ] | Register `0`: Last yank. Register `1`: Last deletion. Register `2`: Second last deletion. And so on. Think of registers `1`-`9` as a read-only [queue](https://en.wikipedia.org/wiki/Queue_(abstract_data_type)) with 9 elements. | 497 | | Small delete | `-` | vim | [ ] | Last deletion that was less than one line. | 498 | | Named | `a` to `z`, `A` to `Z` | user | [ ] | If you yank to register `a`, you replace its text. If you yank to register `A`, you append to the text in register `a`. | 499 | | Read-only | `:`, `.`, `%` | vim | [x] | `:`: Last command, `.`: Last inserted text, `%`: Current filename. | 500 | | Alternate buffer | `#` | vim | [ ] | Most of the time the previously visited buffer of the current window. See `:h alternate-file` | 501 | | Expression | `=` | user | [ ] | Evaluation of the VimL expression that was yanked. E.g. do this in insert mode: `=5+5` and "10" will be inserted in the buffer. | 502 | | Selection | `+`, `*` | vim | [ ] | `*` and `+` are the [clipboard](#clipboard) registers. | 503 | | Drop | `~` | vim | [x] | From last drag'n'drop. | 504 | | Black hole | `_` | vim | [ ] | If you don't want any other registers implicitly affected. E.g. `"_dd` deletes the current line without affecting registers `"`, `1`, `+`, `*`. | 505 | | Last search pattern | `/` | vim | [ ] | Last pattern used with `/`, `?`, `:global`, etc. | 506 | 507 | Each register that is not readonly can be set by the user: 508 | 509 | ```vim 510 | :let @/ = 'register' 511 | ``` 512 | 513 | Afterwards n would jump to the next occurrence of "register". 514 | 515 | There are numerous exceptions when registers get implicitly filled, so be sure 516 | to read `:h registers`. 517 | 518 | Yank with `y` and paste with `p`/`P`, but mind that Vim distinguishes between 519 | characterwise and linewise visual selections. See `:h linewise`. 520 | 521 | **Example: linewise** 522 | 523 | `yy` (or just `Y`) yanks the current line, move the cursor somewhere else, use 524 | `p` to paste below the current line `P` for pasting above it. 525 | 526 | **Example: charwise** 527 | 528 | Yank the first word with `0yw`, move somewhere else, paste after the cursor on 529 | the current line with `p` and before the cursor with `P`. 530 | 531 | **Example: explicit naming of register** 532 | 533 | `"aY` yanks the current line into register `a`. Move to another line. `"AY` 534 | appends the current line to register `a`. 535 | 536 | I suggest playing around with all these registers a bit and constantly checking 537 | `:reg`, so you can see what's actually happening. 538 | 539 | **Fun fact**: In Emacs "yanking" stands for pasting (or _reinserting previously 540 | killed text_) not copying. 541 | 542 | ## Ranges 543 | 544 | Ranges are pretty easy to understand, but many Vimmers don't know about their 545 | full potential. 546 | 547 | - Many commands take ranges. 548 | - An address denotes a certain line. 549 | - A range is either a single address or a pair of addresses separated by either 550 | `,` or `;`. 551 | - Ranges tell commands which lines to act on. 552 | - Most commands act only on the current line by default. Notable exceptions are 553 | `:write` and `:global` which act on all lines. 554 | 555 | The usage of ranges is pretty intuitive, so here are some examples (using `:d` 556 | as short form of `:delete`): 557 | 558 | | Command | Lines acted on | 559 | |---------|----------------| 560 | | `:d` | Current line. | 561 | | `:.d` | Current line. | 562 | | `:1d` | First line. | 563 | | `:$d` | Last line. | 564 | | `:1,$d` | All lines. | 565 | | `:%d` | All lines (syntactic sugar for `1,$`). | 566 | | `:.,5d` | Current line to line 5. | 567 | | `:,5d` | Also current line to line 5. | 568 | | `:,+3d` | Current line and the next 3 lines. | 569 | | `:1,+3d` | First line to current line + 3. | 570 | | `:,-3d` | Current line and the last 3 lines. (Vim will prompt you, since this is a reversed range.) | 571 | | `:3,'xdelete` | Lines 3 to the line marked by [mark](#marks) x. | 572 | | `:/^foo/,$delete` | From the next line that starts with "foo" to the end. | 573 | | `:/^foo/+1,$delete` | From the line after the line that starts with "foo" to the end. | 574 | 575 | Note that instead of `,`, `;` can be used as a separator. The difference is that 576 | in the case of `from,to`, the _to_ is relative to the current line, but when 577 | using `from;to`, the _to_ is relative to the address of _from_! Assuming you're 578 | on line 5, `:1,+1d` would delete lines 1 to 6, whereas `:1;+1d` would only 579 | delete lines 1 and 2. 580 | 581 | The `/` address can be preceded with another address. This allows you to _stack_ 582 | patterns, e.g.: 583 | 584 | ```vim 585 | :/foo//bar//quux/d 586 | ``` 587 | 588 | This would delete the first line containing "quux" after the first line 589 | containing "bar" after the first line containing "foo" after the current line. 590 | 591 | Sometimes Vim automatically prepends the command-line with a range. E.g. start a 592 | visual line selection with `V`, select some lines and type `:`. The command-line 593 | will be populated with the range `'<,'>`, which means the following command will 594 | use the previously selected lines as a range. (This is also why you sometimes 595 | see mappings like `:vnoremap foo :command`. Here `` is used to remove 596 | the range, because Vim will throw an error when giving a range to a command that 597 | doesn't support it.) 598 | 599 | Another example is using `!!` in normal mode. This will populate the 600 | command-line with `:.!`. If followed by an external program, that program's 601 | output would replace the current line. So you could replace the current 602 | paragraph with the output of ls by using `:?^$?+1,/^$/-1!ls`. Fancy! 603 | 604 | Help: 605 | 606 | ``` 607 | :h cmdline-ranges 608 | :h 10.3 609 | ``` 610 | 611 | ## Marks 612 | 613 | You use marks to remember a position, that is line number and column, in a file. 614 | 615 | | Marks | Set by.. | Usage | 616 | |-------|----------|-------| 617 | | `a` - `z` | User | Local to file, thus only valid within one file. Jumping to a lowercase mark, means jumping within the current file. | 618 | | `A` - `Z` | User | Global, thus valid between files. Also called _file marks_. Jumping to a file mark may switch to another buffer. | 619 | | `0` - `9` | viminfo | `0` is the position when the viminfo file was written last. In practice this means when the last Vim process ended. `1` is the position of when the second last Vim process ended and so on. | 620 | 621 | Put `'`/`g'` or `` ` ``/`` g` `` in front of a mark to form a motion. 622 | 623 | Use `mm` to remember the current position with mark "m". Move around the file 624 | and then jump back via `'m` (first non-blank) or `` `m `` (exact column). 625 | Lowercase marks will be remembered after exiting Vim, if you tell your viminfo 626 | file to do so, see `:h viminfo-'`. 627 | 628 | Use `mM` to remember the current position with file mark "M". Switch to another 629 | buffer and switch back via `'M` or `` `M ``. 630 | 631 | Other motions include: 632 | 633 | | Motion | Jump to.. | 634 | |------------------|-----------| 635 | | `'[`, `` `[ `` | First line or character of previously changed or yanked text. | 636 | | `']`, `` `] `` | Last line or character of previously changed or yanked text. | 637 | | `'<`, `` `< `` | Beginning line or character of last visual selection. | 638 | | `'>`, `` `> `` | Ending line or character of last visual selection. | 639 | | `''`, ``` `` ``` | Position before the latest jump. | 640 | | `'"`, `` `" `` | Position when last exiting the current buffer. | 641 | | `'^`, `` `^ `` | Position where last insertion stopped. | 642 | | `'.`, `` `. `` | Position where last change was made. | 643 | | `'(`, `` `( `` | Start of current sentence. | 644 | | `')`, `` `) `` | End of current sentence. | 645 | | `'{`, `` `{ `` | Start of current paragraph. | 646 | | `'}`, `` `} `` | End of current paragraph. | 647 | 648 | Marks can also be used in a [range](#ranges). You probably saw this before and 649 | wondered what it means: Select some text in visual mode and do `:`, the 650 | command-line will be prepended with `:'<,'>`, which means the following command 651 | would get a range that denotes the visual selection. 652 | 653 | Use `:marks` to list all marks. Read everything in `:h mark-motions`. 654 | 655 | ## Completion 656 | 657 | Vim provides many kinds of insert mode completions. If there are multiple 658 | matches, a popup menu will let you navigate to the match of your choice. 659 | 660 | Typical kinds of completion are tags, functions from imported modules or 661 | libraries, file names, dictionary or simply words from the current buffer. 662 | 663 | Vim provides a mapping for each kind of completion and they all start with 664 | `` (remember to use them in insert mode): 665 | 666 | | Mapping | Kind | Help | 667 | |---------|------|--------------| 668 | | `` | whole lines | `:h i^x^l` | 669 | | `` | keywords from current file | `:h i^x^n` | 670 | | `` | keywords from `'dictionary'` option | `:h i^x^k` | 671 | | `` | keywords from `'thesaurus'` option | `:h i^x^t` | 672 | | `` | keywords from current and included files | `:h i^x^i` | 673 | | `` | tags | `:h i^x^]` | 674 | | `` | file names | `:h i^x^f` | 675 | | `` | definitions or macros | `:h i^x^d` | 676 | | `` | Vim commands | `:h i^x^v` | 677 | | `` | user defined (as specified in `'completefunc'`) | `:h i^x^u` | 678 | | `` | omni completion (as specified in `'omnifunc'`) | `:h i^x^o` | 679 | | `s` | spelling suggestions | `:h i^Xs` | 680 | 681 | People might be confused about the difference between user defined completion 682 | and omni completion, but technically they do the same thing. They take a 683 | function that inspects the current position and return a list of suggestions. 684 | User defined completion is defined by the user for their own personal purposes. 685 | (Surprise!) It could be anything. Omni completion is meant for filetype-specific 686 | purposes, like completing struct members or class methods, and is often set by 687 | filetype plugins. 688 | 689 | Vim also allows for completing multiple kinds at once by setting the 690 | `'complete'` option. By default that option includes quite a lot, so be sure to 691 | trim it to your taste. You can trigger this completion by using either `` 692 | (next) and `` (previous), which also happen to be the keys used for 693 | choosing entries in the popup menu. See `:h i^n` and `:h 'complete'` for more on 694 | this. 695 | 696 | Be sure to check out `:h 'completeopt'` for configuring the behaviour of the 697 | popup menu. The default is quite sane, but I prefer adding "noselect" as well. 698 | 699 | Help: 700 | 701 | ``` 702 | :h ins-completion 703 | :h popupmenu-keys 704 | :h new-omni-completion 705 | ``` 706 | 707 | ## Motions, operators, text objects 708 | 709 | **Motions** move the cursor. You all know `h`/`j`/`k`/`l`. Or `w` and `b`. Even 710 | `/` is a motion. They also take a count. `2?the` jumps to the second last 711 | occurrence of "the". 712 | 713 | See `:h navigation` and everything below for all available motions. 714 | 715 | **Operators** act on a region of text, e.g. `d`, `~`, `gU`, `>` to name just a 716 | few. They get used in two contexts, either in normal or visual mode. In normal 717 | mode, operators come first followed by a motion, e.g. `>j`. In visual mode, 718 | operators simply act on the selection, e.g. `Vjd`. 719 | 720 | Like motions, operators take a count, e.g. `2gUw` makes the rest of the current 721 | word and the next one uppercase. Since motions and operators take counts, 722 | `2gU2w` works just as well and executes `gU2w` twice. 723 | 724 | See `:h operator` for all available operators. Use `:set tildeop` to make `~` 725 | act as an operator. 726 | 727 | **Text objects** act on the surrounding area, opposed to motions that act into 728 | one direction. Actually they work on objects, e.g. a whole word, a whole 729 | sentence, everything between parentheses, and so on. 730 | 731 | Text objects can't be used to move the cursor in normal mode, because even the 732 | most-skilled cursors can't jump into two directions at the same time. It works 733 | in visual mode though, because then one side of the object is already selected 734 | and the cursor simply jumps to the other side. 735 | 736 | Text objects start with either `i` (think _inner_) or `a` (think _around_) 737 | followed by a character denoting the object. With `i` it only acts on the object 738 | itself, with `a` on the object plus trailing whitespace. E.g. `diw` deletes the 739 | current word and `ci(` changes everything between parentheses. 740 | 741 | Text objects take a count. Imagine `((( )))` and the cursor on or between the 742 | most inner parentheses, then `d2a(` will remove the 2 inner pairs of parentheses 743 | and everything in between. 744 | 745 | See `:h text-objects` for all available text objects. 746 | 747 | ## Autocmds 748 | 749 | You can trigger an action after many events in Vim, such as a buffer being 750 | saved or Vim having started up, by so-called _autocmds_. 751 | 752 | Vim relies extensively on autocmds. Don't believe me? Check `:au`, but don't let 753 | the output overwhelm you. These are all the autocmds that are in effect right 754 | now! 755 | 756 | See `:h {event}` for a quick overview of all available events and `:h 757 | autocmd-events-abc` for more details. 758 | 759 | A typical example would be filetype-specific settings: 760 | 761 | ```vim 762 | autocmd FileType ruby setlocal shiftwidth=2 softtabstop=2 comments-=:# 763 | ``` 764 | 765 | But how does a buffer even know that it contains Ruby code? Because another 766 | autocmd detected it as that and set the filetype accordingly which again 767 | triggered the `FileType` event. 768 | 769 | One of the first things everyone adds to their vimrc is `filetype on`. This 770 | simply means that `filetype.vim` is read at startup which sets autocmds for 771 | almost all filetypes under the sun. 772 | 773 | If you're brave enough, have a look at it: `:e $VIMRUNTIME/filetype.vim`. Search 774 | for "Ruby" and you'll find that Vim simply uses the file extension `.rb` to 775 | detect Ruby files: 776 | 777 | **NOTE**: Autocmds of the same event are executed in the order they were 778 | created. `:au` shows them in the correct order. 779 | 780 | ```vim 781 | au BufNewFile,BufRead *.rb,*.rbw setf ruby 782 | ``` 783 | 784 | The `BufNewFile` and `BufRead` events in this case are hardcoded in the C 785 | sources of Vim and get emitted every time you open a file via `:e` and similar 786 | commands. Afterwards all the hundreds of filetypes from `filetype.vim` are 787 | tested for. 788 | 789 | Putting it in a nutshell, Vim makes heavy use of events and autocmds but also 790 | exposes a clean interface to hook into that event-driven system for 791 | customization. 792 | 793 | Help: `:h autocommand` 794 | 795 | ## Changelist, jumplist 796 | 797 | The positions of the last 100 changes are kept in the **changelist**. Several 798 | small changes on the same line will be merged together, but the position will be 799 | that of the last change nevertheless (in case you added something in the middle 800 | of the line). 801 | 802 | Every time you jump, the position _before_ the jump is remembered in the 803 | **jumplist**. A jumplist has up to 100 entries. Each window has its own 804 | jumplist. When you split a window, the jumplist is copied. 805 | 806 | A jump is one of the following commands: `'`, `` ` ``, `G`, `/`, `?`, `n`, `N`, 807 | `%`, `(`, `)`, `[[`, `]]`, `{`, `}`, `:s`, `:tag`, `L`, `M`, `H` and commands 808 | that start editing a new file. 809 | 810 | | List | List all entries | Go to older position | Go to newer position | 811 | |------------|------------------|----------------------|----------------------| 812 | | jumplist | `:jumps` | `[count]` | `[count]` | 813 | | changelist | `:changes` | `[count]g;` | `[count]g,` | 814 | 815 | When you list all entries, a marker `>` will be used to show the current 816 | position. Usually that will be below position 1, the latest position. 817 | 818 | If you want both lists to persist after restarting Vim, you need to use the 819 | viminfo file and `:h viminfo-'`. 820 | 821 | **NOTE**: The position before the latest jump is also kept as a [mark](#marks) 822 | and can be jumped to via ``` `` ``` or `''`. 823 | 824 | Help: 825 | 826 | ``` 827 | :h changelist 828 | :h jumplist 829 | ``` 830 | 831 | ## Undo tree 832 | 833 | The latest changes to the text state are remembered. You can use _undo_ to 834 | revert changes and _redo_ to reapply previously reverted changes. 835 | 836 | The important bit to understand it that the data structure holding recent 837 | changes is not a 838 | [queue](https://en.wikipedia.org/wiki/Queue_(abstract_data_type)) but a 839 | [tree](https://en.wikipedia.org/wiki/Tree_(data_structure))! Your changes are 840 | nodes in the tree and each (but the top node) has a parent node. Each node keeps 841 | information about the changed text and time. A branch is a series of nodes that 842 | starts from any node and goes up to the top node. New branches get created when 843 | you undo a change and then insert something else. 844 | 845 | ``` 846 | ifoo 847 | obar 848 | obaz 849 | u 850 | oquux 851 | ``` 852 | 853 | Now you have 3 lines and the undo tree looks like this: 854 | 855 | ``` 856 | foo(1) 857 | / 858 | bar(2) 859 | / \ 860 | baz(3) quux(4) 861 | ``` 862 | 863 | The undo tree has 4 changes. The numbers represent the _time_ the nodes were 864 | created. 865 | 866 | Now there are two ways to traverse this tree, let's call them _branch-wise_ and 867 | _time-wise_. 868 | 869 | Undo (`u`) and redo (``) work branch-wise. They go up and down the current 870 | branch. `u` will revert the text state to the one of node "bar". Another `u` 871 | will revert the text state even further, to the one of node "foo". Now `` 872 | goes back to the state of node "bar" and another `` to the state of node 873 | "quux". (There's no way to reach node "baz" using branch-wise commands anymore.) 874 | 875 | Opposed to this, `g-` and `g+` work time-wise. Thus, `g-` won't revert to the 876 | state of node "bar", like `u` does, but to the chronologically previous state, 877 | node "baz". Another `g-` would revert the state to the one of node "bar" and so 878 | on. Thus, `g-` and `g+` simply go back and forth in time, respectively. 879 | 880 | | Command / Mapping | Action | 881 | |-------------------|--------| 882 | | `[count]u`, `:undo [count]` | Undo [count] changes. | 883 | | `[count]`, `:redo` | Redo [count] changes. | 884 | | `U` | Undo all changes to the line of the latest change. | 885 | | `[count]g-`, `:earlier [count]?` | Go to older text state [count] times. The "?" can be either "s", "m", "h", "d", or "f". E.g. `:earlier 2d` goes to the text state from 2 days ago. `:earlier 1f` will go to the state of the latest file save. | 886 | | `[count]g+`, `:later [count]?` | Same as above, but other direction. | 887 | 888 | The undo tree is kept in memory and will be lost when Vim quits. See [Undo 889 | files](#undo-files) for how to enable persistent undo. 890 | 891 | If you're confused by the undo tree, 892 | [undotree](https://github.com/mbbill/undotree) does a great job at visualizing 893 | it. 894 | 895 | Help: 896 | 897 | ``` 898 | :h undo.txt 899 | :h usr_32 900 | ``` 901 | 902 | ## Quickfix and location lists 903 | 904 | The quickfix list is a data structure that holds file positions. Essentially, 905 | each entry in the quickfix list consists of a file path, a line number and 906 | optional column, and a description. 907 | 908 | Typical use cases are assembling compiler errors or results of a grep tool. 909 | 910 | Vim has a special type of buffer for showing the quickfix list: the quickfix 911 | buffer. Each line in the quickfix buffer shows one entry from the quickfix list. 912 | 913 | Usually you open a new window to display the quickfix list: the quickfix window. 914 | When that happens, the last window gets associated with the quickfix window. 915 | 916 | In the quickfix buffer `` opens the selected entry in the associated window 917 | and `` in a new window. 918 | 919 | The quickfix list was named after the "quick fix" feature from the [Aztec C 920 | compiler](https://en.wikipedia.org/wiki/Aztec_C). 921 | 922 | Actually there are two kinds of lists: quickfix and location lists. They behave 923 | almost the same, but have the follwing differences: 924 | 925 | - There is only one quickfix list. There can be multiple location lists; one per 926 | window. 927 | - They use slightly different commands for navigation. 928 | 929 | | Action | Quickfix | Location | 930 | |----------------|--------------|--------------| 931 | | open window | `:copen` | `:lopen` | 932 | | close window | `:cclose` | `:lclose` | 933 | | next entry | `:cnext` | `:lnext` | 934 | | previous entry | `:cprevious` | `:lprevious` | 935 | | first entry | `:cfirst` | `:lfirst` | 936 | | last entry | `:clast` | `:llast` | 937 | 938 | Mind that the quickfix and location windows don't need to be open for these 939 | commands to work. 940 | 941 | See `:h quickfix` for more information and a full list of commands. 942 | 943 | For conciseness, _quickfix_ and _location_ are often abbreviated as _qf_ and 944 | _loc_ respectively. 945 | 946 | **Example**: 947 | 948 | Let us use our good old friend `grep` for searching the files in the current 949 | directory recursively for a certain query and put the results in the quickfix 950 | list. 951 | 952 | ```vim 953 | :let &grepprg = 'grep -Rn $* .' 954 | :grep! foo 955 | 956 | :copen 957 | ``` 958 | 959 | Assuming any files contained the string "foo", it should be shown now in the 960 | quickfix window. 961 | 962 | ## Macros 963 | 964 | Vim allows _recording_ typed characters into a [register](#registers). It's a 965 | great way to automate certain tasks on the fly. (For more elaborate tasks, Vim 966 | scripting should be used instead.) 967 | 968 | - Start recording by typing `q` followed by the register, e.g. `q`. (The 969 | command-line will signify this via "recording @q".) 970 | - Stop recording by hitting `q` once again. 971 | - Execute the macro via `[count]@q`. 972 | - Repeat the last used macro via `[count]@@`. 973 | 974 | **Example 1:** 975 | 976 | Insert a line and repeat it 10 times: 977 | 978 | ``` 979 | qq 980 | iabc 981 | q 982 | 10@q 983 | ``` 984 | 985 | (The same could be done without macros: `oabc10.`) 986 | 987 | **Example 2:** 988 | 989 | For adding line numbers in front of all lines, start on the first line and add 990 | "1. " to it manually. Increment the number under the cursor by using ``, 991 | displayed as `^A`. 992 | 993 | ``` 994 | qq 995 | 0yf jP0^A 996 | q 997 | 1000@q 998 | ``` 999 | 1000 | Here we simply hope that the file doesn't contain more than 1000 lines when 1001 | using `1000@q`, but we can also use a _recursive macro_, which executes until 1002 | the macro can't be applied to a line anymore: 1003 | 1004 | ``` 1005 | qq 1006 | 0yf jP0^A@q 1007 | q 1008 | @q 1009 | ``` 1010 | 1011 | (The same could be done without macros: `:%s/^/\=line('.') . '. '`) 1012 | 1013 | Mind that I also show how to achieve the same without using macros, but this 1014 | mostly works only for such simple examples. For more complex automation, macros 1015 | are the bomb! 1016 | 1017 | Also see: [Quickly edit your macros](#quickly-edit-your-macros) 1018 | 1019 | Help: 1020 | 1021 | ``` 1022 | :h recording 1023 | :h 'lazyredraw' 1024 | ``` 1025 | 1026 | ## Colorschemes 1027 | 1028 | Colorschemes are the way to style your Vim. Vim consists of many components and 1029 | each of those can be customized with different colors for the foreground, 1030 | background and a few other attributes like bold text etc. They can be set like 1031 | this: 1032 | 1033 | ```vim 1034 | :highlight Normal ctermbg=1 guibg=red 1035 | ``` 1036 | 1037 | This would paint the background of the editor red. See `:h :highlight` for more 1038 | information. 1039 | 1040 | So, colorschemes are mostly collections of `:highlight` commands. 1041 | 1042 | Actually, most colorschemes are really 2 colorschemes! The example above sets 1043 | colors via `ctermbg` and `guibg`. The former definition (`cterm*`) will only be 1044 | used if Vim was started in a terminal emulator, e.g. xterm. The latter (`gui*`) 1045 | will be used in graphical environments like gvim or MacVim. 1046 | 1047 | If you ever happen to use a colorscheme in terminal Vim and the colors don't 1048 | look like the ones in the screenshot at all, chances are that the colorscheme 1049 | only defines colors for the GUI. Conversely, if you use a graphical Vim (e.g. 1050 | gvim or MacVim) and the colors look off, the colorscheme might only define 1051 | colors for the terminal. 1052 | 1053 | The latter case can be "solved" by enabling true colors in Neovim or Vim 1054 | 7.4.1830 and newer. This makes terminal Vim use the GUI definitions instead, but 1055 | also requires the terminal emulator itself and all software in between (e.g. 1056 | tmux) to be capable of handling true colors. ([This 1057 | gist](https://gist.github.com/XVilka/8346728) gives a good overview about the 1058 | topic.) 1059 | 1060 | Help: 1061 | 1062 | - `:h 'termguicolors'` 1063 | - [List of colorschemes](PLUGINS.md#colorschemes-1) 1064 | - [Cosmetic changes to colorschemes](#cosmetic-changes-to-colorschemes) 1065 | 1066 | ## Folding 1067 | 1068 | Every text (or source code) has a certain structure. If you have a structure, it 1069 | means you have regions of logically separated text. Folding allows to "fold" 1070 | such a region into a single line and displaying a short description. There are 1071 | many commands that act on these regions called _folds_. Folds can be nested. 1072 | 1073 | Vim distinguishes between several types of fold methods: 1074 | 1075 | | 'foldmethod' | Usage | 1076 | |--------------|-------| 1077 | | diff | Used in diff windows to fold unchanged text. | 1078 | | expr | Uses `'foldexpr'` to basically create a new fold method. | 1079 | | indent | Folds based on indentation. | 1080 | | manual | Create folds yourself via `zf`, `zF`, and `:fold`. | 1081 | | marker | Folds based on markers in the text (often in comments). | 1082 | | syntax | Folds based on syntax, e.g. folding `if` blocks. | 1083 | 1084 | **NOTE**: Folding can be computationally intensive! If you experience any 1085 | performance drawbacks (small delays when typing), have a look at 1086 | [FastFold](https://github.com/Konfekt/FastFold), which prevents Vim from 1087 | updating folds when it's not needed. 1088 | 1089 | Help: 1090 | 1091 | ``` 1092 | :h usr_28 1093 | :h folds 1094 | ``` 1095 | 1096 | ## Sessions 1097 | 1098 | If you save a **view** (`:h :mkview`), the current state of the window (and 1099 | options and mappings) gets saved for later use (`:h :loadview`). 1100 | 1101 | A **session** saves the views of all windows plus global settings. It basically 1102 | makes a snapshot of your current Vim instance and saves it in a session file. 1103 | Let me stress this: it saves the current state; everything done after saving a 1104 | session won't be part of the session file. To "update" a session, simply write 1105 | it out again. 1106 | 1107 | This makes it perfect for saving your _projects_ and easy to switch between 1108 | them. 1109 | 1110 | Try it right now! Open a few windows and tabs and do `:mksession Foo.vim`. If 1111 | you omit the filename, `Session.vim` will be assumed. The file will be saved to 1112 | the current working directory, check `:pwd`. Restart Vim and do `:source 1113 | Foo.vim` and voilà, the buffer list, window layout, mappings, working directory 1114 | etc. should all be the same as before you saved the session. Do some more work 1115 | and update the session by overwriting the already existing session file with 1116 | `:mksession! Foo.vim`. 1117 | 1118 | Note that a session file is really just a collection of Vim commands that are 1119 | supposed to restore a certain state of a Vim instance, so feel free to take a 1120 | look at it: `:vs Foo.vim`. 1121 | 1122 | You can tell Vim what things to save in a session by setting `'sessionoptions'`. 1123 | 1124 | For scripting purposes Vim keeps the name of the last sourced or written session 1125 | in the internal variable `v:this_session`. 1126 | 1127 | Help: 1128 | 1129 | ``` 1130 | :h Session 1131 | :h 'sessionoptions' 1132 | :h v:this_session 1133 | ``` 1134 | 1135 | ## Locality 1136 | 1137 | Many of the concepts mentioned above also have _local_ counterparts: 1138 | 1139 | | Global | Local | Scope | Help | 1140 | |--------|-------|-------|------| 1141 | | `:set` | `:setlocal` | buffer or window | `:h local-options` | 1142 | | `:map` | `:map ` | buffer | `:h :map-local` | 1143 | | `:autocmd` | `:autocmd * ` | buffer | `:h autocmd-buflocal` | 1144 | | `:cd` | `:lcd` | window | `:h :lcd` | 1145 | | `` | `` | buffer | `:h maplocalleader` | 1146 | 1147 | [Variables also have different scopes](https://vimhelp.appspot.com/usr_41.txt.html#41.2). 1148 | 1149 | # Usage 1150 | 1151 | ## Getting help offline 1152 | 1153 | Vim comes with great documentation in the form of single text files with a 1154 | special layout. Vim uses a system based on tags for accessing certain parts of 1155 | those help files. 1156 | 1157 | First of all, read this: `:help :help`. This will open the file 1158 | `$VIMRUNTIME/doc/helphelp.txt` in a new window and jump to the `:help` tag 1159 | within that file. 1160 | 1161 | A few simple rules: 1162 | 1163 | - options are enclosed in single quotes, e.g. `:h 'textwidth'` 1164 | - VimL functions end in `()`, e.g. `:h reverse()` 1165 | - commands start with `:`, e.g. `:h :echo` 1166 | 1167 | You can use `` (this is ctrl+d) to list all tags that 1168 | match the currently entered query. E.g. `:h tab` will get you a list of all 1169 | tags from `tab` over `'softtabstop'` to `setting-guitablabel`. 1170 | 1171 | You want to list all VimL functions? Simple: `:h ()`. You want to list all 1172 | VimL functions that concern windows? `:h win*()`. 1173 | 1174 | This quickly becomes second nature, but especially in the beginning, you 1175 | sometimes don't know any part of the tag you are looking for. You can only 1176 | imagine some keywords that could be involved. `:helpgrep` to the rescue! 1177 | 1178 | ``` 1179 | :helpgrep backwards 1180 | ``` 1181 | 1182 | This will look for "backwards" in all documentation files and jump to the first 1183 | match. The matches will be assembled in the quickfix list. Use `:cn`/`:cp` to 1184 | jump to the next/previous match. Or use `:copen` to open the quickfix window, 1185 | navigate to an entry and hit `` to jump to that match. See `:h quickfix` for 1186 | the whole truth. 1187 | 1188 | ## Getting help offline (alternative) 1189 | 1190 | This list was compiled by @chrisbra, one of the most active Vim developers, and 1191 | posted to [vim_dev](https://groups.google.com/forum/#!forum/vim_dev). 1192 | 1193 | It's reposted here with minor changes. 1194 | 1195 | --- 1196 | 1197 | If you know what you are looking for, it is usually easier to search for it 1198 | using the help system, because the subjects follow a certain style guide. 1199 | 1200 | Also, the help has the advantage of belonging to your particular Vim version, so 1201 | that obsolete topics or topics that have been added later won't turn up. 1202 | 1203 | Therefore, it is essential to learn the help system and the language it uses. 1204 | Here are some examples (not necessarily complete and I might have forgotten 1205 | something). 1206 | 1207 | 1. Options are enclosed in single quotes. So you would use `:h 'list'` to go to 1208 | the help topic for the list option. If you only know, you are looking for a 1209 | certain option, you can also do `:h options.txt` to open the help page which 1210 | describes all option handling and then you can search using regular 1211 | expressions e.g. `/width`. Certain options have their own namespace, e.g. `:h 1212 | cpo-a`, `:h cpo-A`, `:h cpo-b`, and so on. 1213 | 1214 | 2. Normal mode commands are just that. Use `:h gt` to go to the help page for 1215 | the "gt" command. 1216 | 1217 | 3. Regexp items always start with "/", so `:h /\+` takes you to the help item 1218 | for the "\+" quantifier in Vim regexes. If you need to know anything about 1219 | regular expressions, start reading at `:h pattern.txt`. 1220 | 1221 | 4. Key combinations. They usually start with a single letter indicating the mode 1222 | for which they can be used. E.g. `:h i_CTRL-X` takes you to the family of 1223 | CTRL-X commands for insert mode which can be used to auto complete different 1224 | things. Note that certain keys will always be written the same, e.g. Control 1225 | will always be CTRL. Note, for normal mode commands, the "n" is left away, 1226 | e.g. `:h CTRL-A`. In contrast, `:h c_CTRL-R` will describe what CTRL-R does 1227 | when entering commands in the command line and `:h v_Ctrl-A` talks about 1228 | incrementing numbers in visual mode and `:h g_CTRL-A` talks about the g 1229 | command (thus you have to press "g" then ). Here the "g" stand for 1230 | the normal command "g" which always expect a second key before doing 1231 | something similar to the commands starting with "z". 1232 | 1233 | 5. Registers always start with "quote" so use `:h quote` to find out about the 1234 | special ":" register. 1235 | 1236 | 6. Vim script (VimL) is available at `:h eval.txt`. Certain aspects of the 1237 | language are available at `:h expr-X` where 'X' is a single letter, e.g. `:h 1238 | expr-!` will take you to the topic describing the '!' (Not) operator for 1239 | VimL. Also important, see `:h function-list` to find a short description of 1240 | all functions available. 1241 | 1242 | 7. Mappings are talked about in the help page `:h map.txt`. Use `:h mapmode-i` 1243 | to find out about the `:imap` command. Also use `:map-topic` to find out 1244 | about certain subtopics particular for mappings (e.g. `:h :map-local` for 1245 | buffer-local mappings or `:h map_bar` for how the '|' is handled in mappings. 1246 | 1247 | 8. Command definitions are talked about at `:h command-*`, so use :h command-bar 1248 | to find out about the '!' argument for custom commands. 1249 | 1250 | 9. Window management commands always start with CTRL-W, so you find the 1251 | corresponding help at `:h CTRL-W_*` (e.g. `:h CTRL-W_p` for switch to the 1252 | previously accessed window). You can also access `:h windows.txt` and read 1253 | your way through, if you are looking for window handling command. 1254 | 1255 | 10. Ex commands always start with ":", so `:h :s` covers the ":s" command. 1256 | 1257 | 11. Use CTRL-D after typing a topic and let Vim try to complete to all available 1258 | topics. 1259 | 1260 | 12. Use `:helpgrep` to search in all help pages (usually also includes help 1261 | pages by installed plugins). See `:h :helpgrep` for how to use it. Once you 1262 | have searched for a topic, all matches are available in the quickfix (or 1263 | location) window which can be opened with `:copen` or `:lopen`. There you 1264 | can also use `/` to further filter the matches. 1265 | 1266 | 13. `:h helphelp` contains some information on how to use the help. 1267 | 1268 | 14. The user manual. This describes help topics for beginners in a rather 1269 | friendly way. Start at `:h usr_toc.txt` to find the table of content (as you 1270 | might have guessed). Skimming over that help to find certain topics, .e.g 1271 | you will find an entry "Digraphs" and "Entering special characters" in 1272 | chapter 24 (so use `:h usr_24.txt` to go to that particular help page). 1273 | 1274 | 15. Highlighting groups always start with `hl-*`. E.g. `:h hl-WarningMsg` talks 1275 | about the "WarningMsg" highlighting group. 1276 | 1277 | 16. Syntax highlighting is namespaced to ":syn-topic", e.g. `:h :syn-conceal` 1278 | talks about the conceal argument for the :syn command. 1279 | 1280 | 17. Quickfix commands usually start with ":c", while location list commands 1281 | usually start with ":l". 1282 | 1283 | 18. `:h BufWinLeave` talks about the BufWinLeave autocmd. Also, `:h 1284 | autocommands-events` talks about all possible events. 1285 | 1286 | 19. Startup arguments always start with "-", so `:h -f` takes you to the help of 1287 | the "-f" command switch of Vim. 1288 | 1289 | 20. Compiled extra features always start with "+", so `:h +conceal` talks about 1290 | the conceal support. 1291 | 1292 | 21. Error codes can be looked up directly in the help. `:h E297` takes you 1293 | exactly to the description of the error message. Sometimes however, those 1294 | error codes are not described, but rather are listed at the Vim command that 1295 | usually causes this. E.g. `:h hE128` takes you directly to the `:function` 1296 | command. 1297 | 1298 | 22. Documentation for included syntax files is usually available at `:h 1299 | ft-*-syntax`. E.g. `:h ft-c-syntax` talks about the C syntax file and the 1300 | options it provides. Sometimes, additional sections for omni completion (`:h 1301 | ft-php-omni`) or filetype plugins (`:h ft-tex-plugin`) are available. 1302 | 1303 | Also, a link to the user documentation (which describes certain commands more 1304 | from a user perspective and less detailed) will be mentioned at the top of help 1305 | pages if they are available. So `:h pattern.txt` mentions the user guide topics 1306 | `:h 03.9` and `:h usr_27`. 1307 | 1308 | ## Getting help online 1309 | 1310 | If you have an issue you can't resolve or are in need of general guidance, see 1311 | the [vim_use](https://groups.google.com/forum/#!forum/vim_use) mailing list. 1312 | Another great resource is using 1313 | [IRC](https://de.wikipedia.org/wiki/Internet_Relay_Chat). The channel `#vim` on 1314 | [Freenode](https://freenode.net) is huge and usually full of helpful people. 1315 | 1316 | If you want to report a Vim bug, use the 1317 | [vim_dev](https://groups.google.com/forum/#!forum/vim_dev) mailing list. 1318 | 1319 | ## Autocmds in practice 1320 | 1321 | You can trigger any event right now: `:doautocmd BufRead`. 1322 | 1323 | ### User events 1324 | 1325 | Especially for plugins it's useful to create your own "User" events: 1326 | 1327 | ```vim 1328 | function! Chibby() 1329 | " A lot of stuff is happening here. 1330 | " And at last.. 1331 | doautocmd User ChibbyExit 1332 | endfunction 1333 | ``` 1334 | 1335 | Now users of your plugin can execute anything when Chibby finishes running: 1336 | 1337 | ```vim 1338 | autocmd User ChibbyExit call ChibbyCleanup() 1339 | ``` 1340 | 1341 | By the way, if there's no "catching" :autocmd, :doautocmd will output a pesky 1342 | "No matching autocommands" message. That's why many plugins use `silent 1343 | doautocmd ...` instead. But this has the disadvantage, that you can't simply use 1344 | `echo "foo"` in the :autocmd, you have to use `unsilent echo "foo"` instead.. 1345 | 1346 | That's why it's better to check if there even is a receiving autocmd and not 1347 | bothering emitting the event otherwise: 1348 | 1349 | ```vim 1350 | if exists('#User#ChibbyExit') 1351 | doautocmd User ChibbyExit 1352 | endif 1353 | ``` 1354 | 1355 | Help: `:h User` 1356 | 1357 | ### Nested autocmds 1358 | 1359 | By default, autocmds do not nest! If an autocmd executes a command, which in 1360 | turn would usually trigger another event, it won't happen. 1361 | 1362 | Let's say every time you start Vim, you want to automatically open your vimrc: 1363 | 1364 | ```vim 1365 | autocmd VimEnter * edit $MYVIMRC 1366 | ``` 1367 | 1368 | When you now start Vim, it will open your vimrc, but the first thing you'll 1369 | notice is that there won't be any highlighting although usually there would be. 1370 | 1371 | The problem is that `:edit` in your non-nested autocmd won't trigger the 1372 | "BufRead" event, so the filetype never gets set to "vim" and 1373 | `$VIMRUNTIME/syntax/vim.vim` never sourced. See `:au BufRead *.vim`. Use this 1374 | instead: 1375 | 1376 | ```vim 1377 | autocmd VimEnter * nested edit $MYVIMRC 1378 | ``` 1379 | 1380 | Help: `:h autocmd-nested` 1381 | 1382 | ## Clipboard 1383 | 1384 | Required [features](#what-kind-of-vim-am-i-running): `+clipboard` and optionally 1385 | `+xterm_clipboard` if you want to use the `'clipboard'` option on a Unix system 1386 | with a Vim that doesn't have GUI support. 1387 | 1388 | Help: 1389 | 1390 | ``` 1391 | :h 'clipboard' 1392 | :h gui-clipboard 1393 | :h gui-selections 1394 | ``` 1395 | 1396 | Also see: [Bracketed paste (or why do I have to set 'paste' all the 1397 | time?)](#bracketed-paste-or-why-do-i-have-to-set-paste-all-the-time) 1398 | 1399 | ### Clipboard usage (Windows, macOS) 1400 | 1401 | Windows comes with a 1402 | [clipboard](https://msdn.microsoft.com/en-us/library/windows/desktop/ms649012(v=vs.85).aspx) 1403 | and macOS comes with a 1404 | [pasteboard](https://developer.apple.com/library/mac/documentation/Cocoa/Conceptual/PasteboardGuide106/Introduction/Introduction.html#//apple_ref/doc/uid/TP40008100-SW1). 1405 | 1406 | Both work like most users would expect them to work. You copy selected text with 1407 | `ctrl+c`/`cmd+c` and paste them in another application with `ctrl+v`/`cmd+v`. 1408 | 1409 | Note that copied text is actually transferred to the clipboard, so you can close 1410 | the application you copied from before pasting in another application without 1411 | problems. 1412 | 1413 | Whenever this happens, the clipboard register `*` gets filled with the 1414 | selection. From Vim use `"*y` and `"*p` to yank and paste from the clipboard 1415 | respectively. 1416 | 1417 | If you don't even want to specify the `*` register all the time, put this in 1418 | your vimrc: 1419 | 1420 | ```vim 1421 | set clipboard=unnamed 1422 | ``` 1423 | 1424 | Usually all yank/delete/put operations fill the `"` register, now the `*` 1425 | register is used for the same operations, therefore simply `y` and `p` will be 1426 | enough. 1427 | 1428 | Let me repeat: Using the option above means that every yank/paste, even when 1429 | only used in the same Vim window, will alter the clipboard. Decide for yourself 1430 | if this is useful or not. 1431 | 1432 | If you're even too lazy to type `y`, you can send every visual selection to the 1433 | clipboard by using these settings: 1434 | 1435 | ```vim 1436 | set clipboard=unnamed,autoselect 1437 | set guioptions+=a 1438 | ``` 1439 | 1440 | Help: 1441 | 1442 | ``` 1443 | :h clipboard-unnamed 1444 | :h autoselect 1445 | :h 'go_a' 1446 | ``` 1447 | 1448 | ### Clipboard usage (Linux, BSD, ...) 1449 | 1450 | If your OS uses [X](http://www.x.org/wiki), things work a bit different. X 1451 | implements the [X Window System 1452 | Protocol](http://www.x.org/releases/X11R7.7/doc/xproto/x11protocol.html) which 1453 | happens to be at major version 11 since 1987, hence X is also often called X11. 1454 | 1455 | Prior, in X10, [cut 1456 | buffers](http://www.x.org/releases/X11R7.7/doc/xorg-docs/icccm/icccm.html#Peer_to_Peer_Communication_by_Means_of_Cut_Buffers) 1457 | were introduced that kind of worked like a _clipboard_ as in copied text was 1458 | actually held by X and it was accessible by all other applications. This 1459 | mechanism still exists in X, but its use is deprecated now and most software 1460 | doesn't use it anymore. 1461 | 1462 | Nowadays data is transferred between applications by the means of 1463 | [selections](http://www.x.org/releases/X11R7.7/doc/xorg-docs/icccm/icccm.html#Peer_to_Peer_Communication_by_Means_of_Selections). 1464 | From the 3 _selection atoms_ defined, only 2 are used in practice: PRIMARY and 1465 | CLIPBOARD. 1466 | 1467 | Selections work roughly like this: 1468 | 1469 | ``` 1470 | Program A: 1471 | Program A: assert ownership of CLIPBOARD 1472 | Program B: 1473 | Program B: note that ownership of CLIPBOARD is hold by Program A 1474 | Program B: request data from Program A 1475 | Program A: respond to request and send data to Program B 1476 | Program B: receives data from Program A and inserts it into the window 1477 | ``` 1478 | 1479 | | Selection | When used? | How to paste? | How to access from Vim? | 1480 | |-----------|------------|---------------|-------------------------| 1481 | | PRIMARY | Selecting text | `middle-click`, `shift+insert` | `*` register | 1482 | | CLIPBOARD | Selecting text and `ctrl+c` | `ctrl+v` | `+` register | 1483 | 1484 | **NOTE**: Selections (no, not even the CLIPBOARD selection) are never kept in 1485 | the X server! Thus, you lose the data copied with `ctrl+c` when the application 1486 | closes. 1487 | 1488 | Use `"*p` to paste the PRIMARY selection or `"+y1G` to yank the entire file to 1489 | the CLIPBOARD selection. 1490 | 1491 | If you happen to access one of the two registers all the time, consider using: 1492 | 1493 | ```vim 1494 | set clipboard^=unnamed " * register 1495 | " or 1496 | set clipboard^=unnamedplus " + register 1497 | ``` 1498 | 1499 | (The `^=` is used to prepend to the default value, `:h :set^=`.) 1500 | 1501 | This will make all yank/delete/put operations use either `*` or `+` instead of 1502 | the unnamed register `"`. Afterwards you can simply use `y` or `p` for accessing 1503 | your chosen X selection. 1504 | 1505 | Help: 1506 | 1507 | ```vim 1508 | :h clipboard-unnamed 1509 | :h clipboard-unnamedplus 1510 | ``` 1511 | 1512 | ## Restore cursor position when opening file 1513 | 1514 | When you open a file, the cursor will be positioned at line 1, column 1. 1515 | Fortunately the viminfo file remembers [marks](#marks). The `"` mark contains 1516 | the position in the buffer where you left off. 1517 | 1518 | ```vim 1519 | autocmd BufReadPost * 1520 | \ if line("'\"") > 1 && line("'\"") <= line("$") | 1521 | \ execute "normal! g`\"" | 1522 | \ endif 1523 | ``` 1524 | 1525 | Read: If the mark `"` contains a line number greater than line 1 but not greater 1526 | than the last line in the file, jump to it. 1527 | 1528 | :h viminfo-' 1529 | :h `quote 1530 | :h g` 1531 | 1532 | ## Temporary files 1533 | 1534 | ### Backup files 1535 | 1536 | Before saving a file, Vim creates a backup file. If writing to disk was 1537 | successful, the backup file will be deleted. 1538 | 1539 | With `:set backup`, the backup will persist. This means, the backup file will 1540 | always have the same content as the original file _before_ the most recent save. 1541 | It's up to you to decide whether this is useful or not. 1542 | 1543 | You can disable backups entirely with `:set nobackup nowritebackup`, but you 1544 | shouldn't need to nowadays. `'writebackup'` is a security feature that makes 1545 | sure that you don't lose the original file in case saving it should ever fail, 1546 | no matter whether you keep the backup file afterwards or not. 1547 | 1548 | If you frequently use Vim to edit huge files, [and you probably 1549 | shouldn't](#editing-huge-files-is-slow), you can exclude those from backups with 1550 | `'backupskip'`. 1551 | 1552 | Vim knows different ways to create a backup: _copying_ and _renaming_. 1553 | 1554 | - **Copying** 1555 | 1. A full copy of the original file is created and used as backup. 1556 | 1. The original file gets emptied and then filled with the content of the 1557 | Vim buffer. 1558 | - **Renaming** 1559 | 1. The original file is renamed to the backup file. 1560 | 1. The content of the Vim buffer gets written to a new file with the name of 1561 | the original file. 1562 | 1563 | See `:h 'backupcopy'` for all the nitty-gritty details. 1564 | 1565 | --- 1566 | 1567 | Demo: 1568 | 1569 | ```vim 1570 | :set backup backupskip= backupdir=. backupext=-backup 1571 | :e /tmp/foo 1572 | ifoo 1573 | :w 1574 | " original file gets created, no need for backup file 1575 | obar 1576 | :w 1577 | " backup file is created, original file gets updated 1578 | ``` 1579 | 1580 | ```diff 1581 | $ diff -u /tmp/foo-backup /tmp/foo 1582 | --- /tmp/foo-backup 2017-04-22 15:05:13.000000000 +0200 1583 | +++ /tmp/foo 2017-04-22 15:05:25.000000000 +0200 1584 | @@ -1 +1,2 @@ 1585 | foo 1586 | +bar 1587 | ``` 1588 | 1589 | --- 1590 | 1591 | :h backup 1592 | :h write-fail 1593 | 1594 | ### Swap files 1595 | 1596 | When editing a file, unsaved changes get written to a swap file. 1597 | 1598 | Get the name of the current swap file with `:swapname`. Disable them with `:set 1599 | noswapfile`. 1600 | 1601 | A swap file gets updated either all 200 characters or when nothing was typed for 1602 | 4 seconds. They get deleted when you stop editing the file. You can change these 1603 | numbers with `:h 'updatecount'` and `:h 'updatetime'`. 1604 | 1605 | If Vim gets killed (e.g. power outage), you lose all changes since the last time 1606 | the file was written to disk, but the swap file won't be deleted. Now, if you 1607 | edit the file again, Vim will offer the chance to recover the file from the swap 1608 | file. 1609 | 1610 | When two people try to edit the same file, the second person will get a notice 1611 | that the swap file already exists. It prevents people from trying to save 1612 | different versions of a file. If you don't want that behaviour, see `:h 1613 | 'directory'`. 1614 | 1615 | :h swap-file 1616 | :h usr_11 1617 | 1618 | ### Undo files 1619 | 1620 | The [undo tree](#undo-tree) is kept in memory and will be lost when Vim quits. 1621 | If you want it to persist, `:set undofile`. This will save the undo file for 1622 | `~/foo.c` in `~/foo.c.un~`. 1623 | 1624 | :h 'undofile' 1625 | :h undo-persistence 1626 | 1627 | ### Viminfo files 1628 | 1629 | When backup, swap, and undo files are all about text state, viminfo files are 1630 | used for saving everything else that would otherwise be lost when quitting Vim. 1631 | The viminfo file keeps histories (command line, search, input), registers, 1632 | marks, buffer list, global variables etc. 1633 | 1634 | By default, the viminfo is written to `~/.viminfo`. 1635 | 1636 | :h viminfo 1637 | :h 'viminfo' 1638 | 1639 | ### Example configuration for temporary files 1640 | 1641 | Put all temporary files in their own directory under `~/.vim/files`: 1642 | 1643 | ```vim 1644 | " create directory if needed 1645 | if !isdirectory($HOME.'/.vim/files') && exists('*mkdir') 1646 | call mkdir($HOME.'/.vim/files') 1647 | endif 1648 | 1649 | " backup files 1650 | set backup 1651 | set backupdir =$HOME/.vim/files/backup/ 1652 | set backupext =-vimbackup 1653 | set backupskip = 1654 | " swap files 1655 | set directory =$HOME/.vim/files/swap// 1656 | set updatecount =100 1657 | " undo files 1658 | set undofile 1659 | set undodir =$HOME/.vim/files/undo/ 1660 | " viminfo files 1661 | set viminfo ='100,n$HOME/.vim/files/info/viminfo 1662 | ``` 1663 | 1664 | ## Editing remote files 1665 | 1666 | Vim comes with the netrw plugin that enables editing remote files. Actually it 1667 | transfers the remote file to a local temporary file via scp, opens a buffer 1668 | using that file, and writes the changes back to the remote file on saving. 1669 | 1670 | This is extremely useful if you want to use your local configuration opposed to 1671 | ssh'ing into a server and use whatever the admins want you to use. 1672 | 1673 | ``` 1674 | :e scp://bram@awesome.site.com/.vimrc 1675 | ``` 1676 | 1677 | If you have a `~/.ssh/config` set up already, this gets used automatically: 1678 | 1679 | ``` 1680 | Host awesome 1681 | HostName awesome.site.com 1682 | Port 1234 1683 | User bram 1684 | ``` 1685 | 1686 | Assuming the above content in `~/.ssh/config`, this works just as well: 1687 | 1688 | ``` 1689 | :e scp://awesome/.vimrc 1690 | ``` 1691 | 1692 | Similar can be done with a `~/.netrc`, see `:h netrw-netrc`. 1693 | 1694 | Make sure to read `:h netrw-ssh-hack` and `:h g:netrw_ssh_cmd`. 1695 | 1696 | --- 1697 | 1698 | Another possibility is using [sshfs](https://wiki.archlinux.org/index.php/Sshfs) 1699 | which uses [FUSE](https://en.wikipedia.org/wiki/Filesystem_in_Userspace) to 1700 | mount a remote filesystem into your local filesystem. 1701 | 1702 | ## Managing plugins 1703 | 1704 | [Pathogen](https://github.com/tpope/vim-pathogen) was the first popular tool for 1705 | managing plugins. Actually it just adjusts the _runtimepath_ (`:h 'rtp'`) to 1706 | include all the things put under a certain directory. You have to clone the 1707 | repositories of the plugins there yourself. 1708 | 1709 | Real plugin managers expose commands that help you to install and update plugins 1710 | from within Vim. 1711 | 1712 | [List of plugin managers](PLUGINS.md#plugin-managers) 1713 | 1714 | ## Block insert 1715 | 1716 | This is a technique to insert the same text on multiple consecutive lines at the 1717 | same time. See this 1718 | [demo](https://raw.githubusercontent.com/mhinz/vim-galore/master/static/images/content-block_insert.gif). 1719 | 1720 | Switch to visual block mode with ``. Afterwards go down for a few lines. 1721 | Hit `I` or `A` and start entering your text. 1722 | 1723 | It might be a bit confusing at first, but text is always entered for the current 1724 | line and only after finishing the current insertion, the same text will be 1725 | applied to all other lines of the prior visual selection. 1726 | 1727 | So a simple example is `3jItext`. 1728 | 1729 | If you have lines of different length and want to append the same text right 1730 | after the end of each line, do this: `3j$Atext`. 1731 | 1732 | Sometime you need to place the cursor somewhere after the end of the current 1733 | line. You can't do that by default, but you can set the `virtualedit` option: 1734 | 1735 | ```vim 1736 | set virtualedit=all 1737 | ``` 1738 | 1739 | Afterwards `$10l` or `90|` work even after the end of the line. 1740 | 1741 | See `:h blockwise-examples` for more info. It might seem complicated at first, 1742 | but quickly becomes second nature. 1743 | 1744 | If you want to get real fancy, have a look at 1745 | [multiple-cursors](https://github.com/terryma/vim-multiple-cursors). 1746 | 1747 | ## Running external programs and using filters 1748 | 1749 | Disclaimer: Vim is single-threaded, so running an external program in the 1750 | foreground will block everything else. Sure, you can use one of Vim's 1751 | programming interfaces, e.g. Lua, and use its thread support, but during that 1752 | time the Vim process is blocked nevertheless. Neovim fixed that by adding a 1753 | proper job API. 1754 | 1755 | (Apparently Bram is thinking about adding job control to Vim as well. If you 1756 | have a very recent version, see `:helpgrep startjob`.) 1757 | 1758 | Use `:!` to start a job. If you want to list the files in the current working 1759 | directory, use `:!ls`. Use `|` for piping in the shell as usual, e.g. `:!ls -1 | 1760 | sort | tail -n5`. 1761 | 1762 | Without a range, the output of `:!` will be shown in a scrollable window. On the 1763 | other hand, if a range is given, these lines will be 1764 | [filtered](https://en.wikipedia.org/wiki/Filter_(software)). This means they 1765 | will be piped to the 1766 | [stdin](https://en.wikipedia.org/wiki/Standard_streams#Standard_input_.28stdin.29) 1767 | of the filter program and after processing be replaced by the 1768 | [stdout](https://en.wikipedia.org/wiki/Standard_streams#Standard_output_.28stdout.29) 1769 | of the filter. E.g. for prepending numbers to the next 5 lines, use this: 1770 | 1771 | :.,+4!nl -ba -w1 -s' ' 1772 | 1773 | Since manually adding the range is quite burdensome, Vim also provides some 1774 | helpers for convenience. As always with ranges, you can also select lines in 1775 | visual mode and then hit `:`. There's also an operator `!` that takes a motion. 1776 | E.g. `!ip!sort` will sort the lines of the current paragraph. 1777 | 1778 | A good use case for filtering is the [Go programming 1779 | language](https://golang.org). The indentation is pretty opinionated, it even 1780 | comes with a filter called `gofmt` for indenting Go source code properly. So 1781 | plugins for Go often provide helper commands called `:Fmt` that basically do 1782 | `:%!gofmt`, so they indent all lines in the file. 1783 | 1784 | People often use `:r !prog` to put the output of prog below the current line, 1785 | which is fine for scripts, but when doing it on the fly, I find it easier to use 1786 | `!!ls` instead, which replaces the current line. 1787 | 1788 | :h filter 1789 | :h :read! 1790 | 1791 | ## Cscope 1792 | 1793 | [Cscope](http://cscope.sourceforge.net/) does more things than 1794 | [ctags](http://ctags.sourceforge.net/), but only supports C (and C++ and Java to 1795 | some extent). 1796 | 1797 | Whereas a tags file only knows where a symbol was defined, a cscope database 1798 | knows much more about your data: 1799 | 1800 | - Where is this symbol defined? 1801 | - Where is this symbol used? 1802 | - What is this global symbol's definition? 1803 | - Where did this variable get its value? 1804 | - Where is this function in the source files? 1805 | - What functions call this function? 1806 | - What functions are called by this function? 1807 | - Where does the message "out of space" come from? 1808 | - Where is this source file in the directory structure? 1809 | - What files include this header file? 1810 | 1811 | ### 1. Build the database 1812 | 1813 | Do this in the root of your project: 1814 | 1815 | ```sh 1816 | $ cscope -bqR 1817 | ``` 1818 | 1819 | This will create 3 files: `cscope{,.in,.po}.out` in the current working 1820 | directory. Think of them as your database. 1821 | 1822 | Unfortunately `cscope` only analyzes `*.[c|h|y|l]` files by default. If you want 1823 | to use cscope for a Java project instead, do this: 1824 | 1825 | ```sh 1826 | $ find . -name "*.java" > cscope.files 1827 | $ cscope -bq 1828 | ``` 1829 | 1830 | ### 2. Add the database 1831 | 1832 | Open a connection to your freshly built database: 1833 | 1834 | ```vim 1835 | :cs add cscope.out 1836 | ``` 1837 | 1838 | Verify that the connection was made: 1839 | 1840 | ```vim 1841 | :cs show 1842 | ``` 1843 | 1844 | (Yes, you can add multiple connections.) 1845 | 1846 | ### 3. Query the database 1847 | 1848 | ```vim 1849 | :cs find 1850 | ``` 1851 | 1852 | E.g. `:cs find d foo` will list all functions that are called by `foo(...)`. 1853 | 1854 | | Kind | Explanation | 1855 | |------|-------------| 1856 | | s | **s**ymbol: find all references to the token | 1857 | | g | **g**lobal: find global definition(s) of the token | 1858 | | c | **c**alls: find all calls to the function | 1859 | | t | **t**ext: find all instances of the text | 1860 | | e | **e**grep: egrep search for the word | 1861 | | f | **f**ile: open the filename | 1862 | | i | **i**ncludes: find files that include the filename | 1863 | | d | **d**epends: find functions called by this function | 1864 | 1865 | I suggest some convenience mappings e.g.: 1866 | 1867 | ```vim 1868 | nnoremap cs :cscope find s =expand('') 1869 | nnoremap cg :cscope find g =expand('') 1870 | nnoremap cc :cscope find c =expand('') 1871 | nnoremap ct :cscope find t =expand('') 1872 | nnoremap ce :cscope find e =expand('') 1873 | nnoremap cf :cscope find f =expand('') 1874 | nnoremap ci :cscope find i ^=expand('')$ 1875 | nnoremap cd :cscope find d =expand('') 1876 | ``` 1877 | 1878 | So, when `:tag` (or ``) jumps to a definition from the tags file, `:cstag` 1879 | does the same, but also takes connected cscope databases into account. The 1880 | option `'cscopetag'` makes `:tag` act like `:cstag` automatically. This is very 1881 | convenient if you already have tag-related mappings. 1882 | 1883 | Help: `:h cscope` 1884 | 1885 | ## MatchIt 1886 | 1887 | Since Vim is written in C, a lot of features assume C-like syntax. By default, 1888 | if your cursor is on `{` or `#endif`, you can use `%` to jump to the 1889 | corresponding `}` or `#ifdef` respectively. 1890 | 1891 | Vim comes bundled with a plugin called matchit.vim which is not enabled by 1892 | default. It makes `%` also cycle through HTML tags, if/else/endif constructs in 1893 | VimL etc. and introduces a few new commands. 1894 | 1895 | #### Installation for Vim 8 1896 | 1897 | ```vim 1898 | " vimrc 1899 | packadd! matchit 1900 | ``` 1901 | 1902 | #### Installation for Vim 7 and older 1903 | 1904 | ```vim 1905 | " vimrc 1906 | runtime macros/matchit.vim 1907 | ``` 1908 | 1909 | Since the documentation of matchit is pretty extensive, I suggest also doing the 1910 | following once: 1911 | 1912 | ```vim 1913 | :!mkdir -p ~/.vim/doc 1914 | :!cp $VIMRUNTIME/macros/matchit.txt ~/.vim/doc 1915 | :helptags ~/.vim/doc 1916 | ``` 1917 | 1918 | #### Small intro 1919 | 1920 | The plugin is ready to use now. See `:h matchit-intro` for the supported 1921 | commands and `:h matchit-languages` for the supported languages. 1922 | 1923 | That said, it's easy to define your own matching pairs: 1924 | 1925 | ```vim 1926 | autocmd FileType python let b:match_words = '\:\:\' 1927 | ``` 1928 | 1929 | Afterwards you can cycle through these 3 statements in any Python file by using 1930 | `%` (forward) or `g%` (backward). 1931 | 1932 | Help: 1933 | 1934 | ``` 1935 | :h matchit-install 1936 | :h matchit 1937 | :h b:match_words 1938 | ``` 1939 | 1940 | ## True colors 1941 | 1942 | Using true colors in a terminal emulator means being able to use 24 bits for RGB 1943 | colors. That makes 16777216 (2^24) colors instead of the usual 256. 1944 | 1945 | As explained [here](#colorschemes), colorschemes can actually be _two_ 1946 | colorschemes by having definitions for terminals (xterm) and for GUIs (gvim). 1947 | This made sense before terminal emulators learned about true colors. 1948 | 1949 | After `:set termguicolors`, Vim starts emitting escape sequences only understood 1950 | by a terminal emulator that supports true colors. When your colors look weird, 1951 | chances are your terminal emulator doesn't support true colors or your 1952 | colorcheme has no GUI colors defined. 1953 | 1954 | Many people use the terminal multiplexer 1955 | [tmux](https://github.com/tmux/tmux/wiki) which basically sits in between the 1956 | terminal emulator and Vim. To make tmux _forward_ the true color escape 1957 | sequences emitted by Vim, you have to put the following in the user's 1958 | `.tmux.conf`: 1959 | 1960 | ``` 1961 | set-option -g default-terminal 'tmux-256color' 1962 | set-option -ga terminal-overrides ',xterm-256color:Tc' 1963 | ``` 1964 | 1965 | - The first line should be the same for most people and denotes the `$TERM` to 1966 | be used _within_ tmux. 1967 | - The second line adds the tmux-specific `Tc` (true color) capability to the 1968 | other terminfo entries of `xterm-256color`. Obviously this assumes that the 1969 | user is using `TERM=xterm-256color` _outside_ of tmux. 1970 | 1971 | So, here is the checklist for enabling true colors: 1972 | 1973 | - Read `:h 'termguicolors'`. 1974 | - Put `set termguicolors` in your vimrc. 1975 | - Make sure your colorscheme has color definitions for GUIs. (It should contain 1976 | lines with `guifg` and `guibg`.) 1977 | - Make sure your terminal emulator of choice supports true colors. 1978 | - Using tmux? Configure it to add the `Tc` capability. 1979 | 1980 | A popular reference for colors in the terminal: 1981 | https://gist.github.com/XVilka/8346728 1982 | 1983 | # Tips 1984 | 1985 | ## Go to other end of selected text 1986 | 1987 | `o` and `O` in a visual selection make the cursor go to the other end. Try with 1988 | blockwise selection to see the difference. This is useful for quickly changing 1989 | the size of the selected text. 1990 | 1991 | ``` 1992 | :h v_o 1993 | :h v_O 1994 | ``` 1995 | 1996 | ## Saner behavior of n and N 1997 | 1998 | The direction of `n` and `N` depends on whether `/` or `?` was used for 1999 | searching forward or backward respectively. This is pretty confusing to me. 2000 | 2001 | If you want `n` to always search forward and `N` backward, use this: 2002 | 2003 | ```vim 2004 | nnoremap n 'Nn'[v:searchforward] 2005 | xnoremap n 'Nn'[v:searchforward] 2006 | onoremap n 'Nn'[v:searchforward] 2007 | 2008 | nnoremap N 'nN'[v:searchforward] 2009 | xnoremap N 'nN'[v:searchforward] 2010 | onoremap N 'nN'[v:searchforward] 2011 | ``` 2012 | 2013 | ## Saner command-line history 2014 | 2015 | If you're anything like me, you're used to going to next and previous items via 2016 | `` and `` respectively. By default, this also works in the 2017 | command-line and recalls older or more recent command-lines from history. 2018 | 2019 | So far, so good. But `` and `` are even smarter! They recall the 2020 | command-line whose beginning matches the current command-line. E.g. `:echo ` 2021 | may change to `:echo "Vim rocks!"`. 2022 | 2023 | Of course, I don't want you to reach for the arrow keys: 2024 | 2025 | ```vim 2026 | cnoremap wildmenumode() ? "\" : "\" 2027 | cnoremap wildmenumode() ? "\" : "\" 2028 | ``` 2029 | 2030 | Here we also distinguish between command-line history and the wildmenu. See `:h 2031 | 'wildmenu'`. 2032 | 2033 | I depend on this behaviour several times a day. 2034 | 2035 | ## Saner CTRL-L 2036 | 2037 | By default, `` clears and redraws the screen (like `:redraw!`). The 2038 | following mapping does the same, plus de-highlighting the matches found via `/`, 2039 | `?` etc., plus fixing syntax highlighting (sometimes Vim loses highlighting due 2040 | to complex highlighting rules), plus force updating the syntax highlighting in 2041 | diff mode: 2042 | 2043 | ```vim 2044 | nnoremap l :nohlsearch:diffupdate:syntax sync fromstart 2045 | ``` 2046 | 2047 | ## Disable audible and visual bells 2048 | 2049 | ```vim 2050 | set noerrorbells 2051 | set novisualbell 2052 | set t_vb= 2053 | ``` 2054 | 2055 | See [Vim Wiki: Disable beeping](http://vim.wikia.com/wiki/Disable_beeping). 2056 | 2057 | ## Quickly move current line 2058 | 2059 | Sometimes I need a quick way to move the current line above or below: 2060 | 2061 | ```vim 2062 | nnoremap [e :execute 'move -1-'. v:count1 2063 | nnoremap ]e :execute 'move +'. v:count1 2064 | ``` 2065 | 2066 | These mappings also take a count, so `2]e` moves the current line 2 lines below. 2067 | 2068 | ## Quickly add empty lines 2069 | 2070 | ```vim 2071 | nnoremap [ :put! =repeat(nr2char(10), v:count1)'[ 2072 | nnoremap ] :put =repeat(nr2char(10), v:count1) 2073 | ``` 2074 | 2075 | Now `5[` inserts 5 blank lines above the current line. 2076 | 2077 | ## Quickly edit your macros 2078 | 2079 | This is a real gem! The mapping takes a register (or `*` by default) and opens 2080 | it in the cmdline-window. Hit `` when you're done editing for setting the 2081 | register. 2082 | 2083 | I often use this to correct typos I did while recording a macro. 2084 | 2085 | ```vim 2086 | nnoremap m :='let @'. v:register .' = '. string(getreg(v:register)) 2087 | ``` 2088 | 2089 | Use it like this `m` or `"qm`. 2090 | 2091 | Notice the use of `` to make sure that the `` is inserted 2092 | literally. See `:h c_^R^R`. 2093 | 2094 | ## Quickly jump to header or source file 2095 | 2096 | This technique can probably be applied to many filetypes. It sets _file marks_ 2097 | (see `:h marks`) when leaving a source or header file, so you can quickly jump 2098 | back to the last accessed one by using `'C` or `'H` (see `:h 'A`). 2099 | 2100 | ```vim 2101 | autocmd BufLeave *.{c,cpp} mark C 2102 | autocmd BufLeave *.h mark H 2103 | ``` 2104 | 2105 | **NOTE**: The info is saved in the viminfo file, so make sure that `:set 2106 | viminfo?` includes `:h viminfo-'`. 2107 | 2108 | ## Quickly change font size in GUI 2109 | 2110 | I think this was taken from tpope's config: 2111 | 2112 | ```vim 2113 | command! Bigger :let &guifont = substitute(&guifont, '\d\+$', '\=submatch(0)+1', '') 2114 | command! Smaller :let &guifont = substitute(&guifont, '\d\+$', '\=submatch(0)-1', '') 2115 | ``` 2116 | 2117 | ## Change cursor style dependent on mode 2118 | 2119 | I like to use a block cursor in normal mode, i-beam cursor in insert mode, and 2120 | underline cursor in replace mode. 2121 | 2122 | ```vim 2123 | if empty($TMUX) 2124 | let &t_SI = "\]50;CursorShape=1\x7" 2125 | let &t_EI = "\]50;CursorShape=0\x7" 2126 | let &t_SR = "\]50;CursorShape=2\x7" 2127 | else 2128 | let &t_SI = "\Ptmux;\\]50;CursorShape=1\x7\\\" 2129 | let &t_EI = "\Ptmux;\\]50;CursorShape=0\x7\\\" 2130 | let &t_SR = "\Ptmux;\\]50;CursorShape=2\x7\\\" 2131 | endif 2132 | ``` 2133 | 2134 | This simply tells Vim to print a certain sequence of characters ([escape 2135 | sequence](https://en.wikipedia.org/wiki/Escape_sequence)) when entering/leaving 2136 | insert mode. The underlying terminal, or programs like 2137 | [tmux](https://tmux.github.io) that sit between Vim and the terminal, will 2138 | process and evaluate it. 2139 | 2140 | There's one drawback though: there are many terminal emulator implementations 2141 | and not all use the same sequences for doing the same things. The sequences used 2142 | above might not work with your implementation. Your implementation might not 2143 | even support different cursor styles. Check the documentation. 2144 | 2145 | The example above works with iTerm2. 2146 | 2147 | ## Don't lose selection when shifting sidewards 2148 | 2149 | If you select one or more lines, you can use `<` and `>` for shifting them 2150 | sidewards. Unfortunately you immediately lose the selection afterwards. 2151 | 2152 | You can use `gv` to reselect the last selection (see `:h gv`), thus you can work 2153 | around it like this: 2154 | 2155 | ```vim 2156 | xnoremap < >gv 2158 | ``` 2159 | 2160 | Now you can use `>>>>>` on your visual selection without any problems. 2161 | 2162 | **NOTE**: The same can be achieved using `.`, which repeats the last change. 2163 | 2164 | ## Reload a file on saving 2165 | 2166 | Using [autocmds](#autocmds) you can do anything on saving a file, e.g. sourcing 2167 | it in case of a dotfile or running a linter to check for syntactical errors in 2168 | your source code. 2169 | 2170 | ```vim 2171 | autocmd BufWritePost $MYVIMRC source $MYVIMRC 2172 | autocmd BufWritePost ~/.Xdefaults call system('xrdb ~/.Xdefaults') 2173 | ``` 2174 | 2175 | ## Smarter cursorline 2176 | 2177 | I love the cursorline, but I only want to use it in the current window and not 2178 | when being in insert mode: 2179 | 2180 | ```vim 2181 | autocmd InsertLeave,WinEnter * set cursorline 2182 | autocmd InsertEnter,WinLeave * set nocursorline 2183 | ``` 2184 | 2185 | ## Faster keyword completion 2186 | 2187 | The keyword completion (``/``) tries completing whatever is listed in 2188 | the `'complete'` option. By default, this also includes tags (which can be 2189 | annoying) and scanning all included files (which can be very slow). If you can 2190 | live without these things, disable them: 2191 | 2192 | ```vim 2193 | set complete-=i " disable scanning included files 2194 | set complete-=t " disable searching tags 2195 | ``` 2196 | 2197 | ## Cosmetic changes to colorschemes 2198 | 2199 | Always use a dark gray statusline, no matter what colorscheme is chosen: 2200 | 2201 | ```vim 2202 | autocmd ColorScheme * highlight StatusLine ctermbg=darkgray cterm=NONE guibg=darkgray gui=NONE 2203 | ``` 2204 | 2205 | This triggers every time you use `:colorscheme ...`. If you want it to trigger 2206 | only for a certain colorscheme: 2207 | 2208 | ```vim 2209 | autocmd ColorScheme desert highlight StatusLine ctermbg=darkgray cterm=NONE guibg=darkgray gui=NONE 2210 | ``` 2211 | 2212 | This triggers only for `:colorscheme desert`. 2213 | 2214 | # Commands 2215 | 2216 | Useful commands that are good to know. Use `:h :` to learn more 2217 | about them, e.g. `:h :global`. 2218 | 2219 | ## :global and :vglobal 2220 | 2221 | Execute a command on all matching lines. E.g. `:global /regexp/ print` will use 2222 | `:print` on all lines that contain "regexp". 2223 | 2224 | Fun fact: You probably all know good old grep, the filter program written by Ken 2225 | Thompson. What does it do? It prints all lines matching a certain regular 2226 | expression! Now guess the short form of `:global /regexp/ print`? That's right! 2227 | It's `:g/re/p`. Ken Thompson was inspired by vi's `:global` when he wrote grep. 2228 | 2229 | Despite its name, `:global` only acts on all lines by default, but it also takes 2230 | a range. Assume you want use `:delete` on all lines from the current line to the 2231 | next blank line (matched by the regular expression `^$`) that contain "foo": 2232 | 2233 | ```vim 2234 | :,/^$/g/foo/d 2235 | ``` 2236 | 2237 | For executing commands on all lines that do _not_ match a given pattern, use 2238 | `:global!` or its alias `:vglobal` (think _inVerse_) instead. 2239 | 2240 | ## :normal and :execute 2241 | 2242 | These commands are commonly used in Vim scripts. 2243 | 2244 | With `:normal` you can do normal mode mappings from the command-line. E.g. 2245 | `:normal! 4j` will make the cursor go down 4 lines (without using any custom 2246 | mapping for "j" due to the "!"). 2247 | 2248 | Mind that `:normal` also takes a [range](#ranges), so `:%norm! Iabc` would 2249 | prepend "abc" to every line. 2250 | 2251 | With `:execute` you can mix commands with expressions. Assume you edit a C 2252 | source file and want to switch to its header file: 2253 | 2254 | ```vim 2255 | :execute 'edit' fnamemodify(expand('%'), ':r') . '.h' 2256 | ``` 2257 | 2258 | Both commands are often used together. Assume you want to make the cursor go 2259 | down "n" lines: 2260 | 2261 | ```vim 2262 | :let n = 4 2263 | :execute 'normal!' n . 'j' 2264 | ``` 2265 | 2266 | ## :redir and execute() 2267 | 2268 | Many commands print messages and `:redir` allows to redirect that output. You 2269 | can redirect to files, [registers](#registers) or variables. 2270 | 2271 | ```vim 2272 | :redir => var 2273 | :reg 2274 | :redir END 2275 | :echo var 2276 | :" For fun let's also put it onto the current buffer. 2277 | :put =var 2278 | ``` 2279 | 2280 | In Vim 8 there is an even shorter way: 2281 | 2282 | ```vim 2283 | :put =execute('reg') 2284 | ``` 2285 | 2286 | Help: 2287 | 2288 | ``` 2289 | :h :redir 2290 | :h execute() 2291 | ``` 2292 | 2293 | # Debugging 2294 | 2295 | ## General tips 2296 | 2297 | If you encounter a strange behaviour, try reproducing it like this: 2298 | 2299 | ``` 2300 | vim -u NONE -N 2301 | ``` 2302 | 2303 | This will start Vim without vimrc (thus default settings) and in nocompatible 2304 | mode (which makes it use Vim defaults instead of vi defaults). (See `:h 2305 | --noplugin` for other combinations of what to load at start.) 2306 | 2307 | If you can still reproduce it now, it's most likely a bug in Vim itself! Report 2308 | it to the [vim_dev](https://groups.google.com/forum/#!forum/vim_dev) mailing 2309 | list. Most of the time the issue won't be resolved at this time and you'll have 2310 | to further investigate. 2311 | 2312 | Plugins often introduce new/changed/faulty behaviour. E.g. if it happens on 2313 | saving, check `:verb au BufWritePost` to get a list of potential culprits. 2314 | 2315 | If you're using a plugin manager, comment them out until you find the culprit. 2316 | 2317 | Issue is still not resolved? If it's not a plugin, it must be your other 2318 | settings, so maybe your options or autocmds etc. 2319 | 2320 | Time to use binary search. Repeatedly split the search space in two until you 2321 | find the culprit line. Due to the nature of binary division, it won't take many 2322 | steps. 2323 | 2324 | In practice, it works like this: Put the `:finish` command in the middle of your 2325 | vimrc. Vim will skip everything after it. If it still happens, the problem is in 2326 | the active upper half. Move the `:finish` to the middle of _that_ half. 2327 | Otherwise, the issue is in the inactive lower half. Move the `:finish` to the 2328 | middle of _that_ half. And so on. 2329 | 2330 | ## Verbosity 2331 | 2332 | Another useful way for observing what Vim is currently doing is increasing the 2333 | verbosity level. Currently Vim supports 9 different levels. See `:h 'verbose'` 2334 | for the full list. 2335 | 2336 | ```vim 2337 | :e /tmp/foo 2338 | :set verbose=2 2339 | :w 2340 | :set verbose=0 2341 | ``` 2342 | 2343 | This would show all the files that get sourced, e.g. the undo file or various 2344 | plugins that act on saving. 2345 | 2346 | If you only want increase verbosity for a single command, there's also 2347 | `:verbose`, which simply gets put in front of any other command. It takes the 2348 | verbosity level as count and defaults to 1: 2349 | 2350 | ```vim 2351 | :verb set verbose 2352 | " verbose=1 2353 | :10verb set verbose 2354 | " verbose=10 2355 | ``` 2356 | 2357 | It's very often used with its default verbosity level 1 to show where an option 2358 | was set last: 2359 | 2360 | ```vim 2361 | :verb set ai? 2362 | " Last set from ~/.vim/vimrc 2363 | ``` 2364 | 2365 | Naturally, the higher the verbosity level the more overwhelming the output. But 2366 | fear no more, you can simply redirect the output to a file: 2367 | 2368 | ```vim 2369 | :set verbosefile=/tmp/foo | 15verbose echo "foo" | vsplit /tmp/foo 2370 | ``` 2371 | 2372 | You can also enable verbosity at starting time, with the `-V` option. It 2373 | defaults to verbosity level 10. E.g. `vim -V5`. 2374 | 2375 | ## Profiling startup time 2376 | 2377 | Vim startup feels slow? Time to crunch some numbers: 2378 | 2379 | ``` 2380 | vim --startuptime /tmp/startup.log +q && vim /tmp/startup.log 2381 | ``` 2382 | 2383 | The first column is the most important as it shows the elapsed absolute time. If 2384 | there is a big jump in time between two lines, the second line is either a very 2385 | big file or a file with faulty VimL code that is worth investigating. 2386 | 2387 | ## Profiling at runtime 2388 | 2389 | Required [feature](#what-kind-of-vim-am-i-running): `+profile` 2390 | 2391 | Vim provides a built-in capability for profiling at runtime and is a great way 2392 | to find slow code in your environment. 2393 | 2394 | The `:profile` command takes a bunch of sub-commands for specifying what to 2395 | profile. 2396 | 2397 | If you want to profile _everything_, do this: 2398 | 2399 | :profile start /tmp/profile.log 2400 | :profile file * 2401 | :profile func * 2402 | 2403 | :qa 2404 | 2405 | Vim keeps the profiling information in memory and only writes it out to the 2406 | logfile on exit. (Neovim has fixed this using `:profile dump`). 2407 | 2408 | Have a look at `/tmp/profile.log`. All code that was executed during profiling 2409 | will be shown. Every line, how often it was executed and how much time it took. 2410 | 2411 | Jump to the bottom of the log. Here are two different sections `FUNCTIONS SORTED 2412 | ON TOTAL TIME` and `FUNCTIONS SORTED ON SELF TIME` that are worth gold. At a 2413 | quick glance you can see which functions are taking the longest. 2414 | 2415 | You can use `:profile` during startup as well: 2416 | 2417 | $ vim --cmd 'prof start prof.log | prof file * | prof func *' test.c 2418 | :q 2419 | $ tail -50 prof.log 2420 | 2421 | ## Debugging Vim scripts 2422 | 2423 | If you ever used a command-line debugger before, `:debug` will quickly feel 2424 | familiar. 2425 | 2426 | Simply prepend `:debug` to any other command and you'll be put into debug mode. 2427 | That is, the execution will stop at the first line about to be executed and that 2428 | line will be displayed. 2429 | 2430 | See `:h >cont` and below for the 6 available debugger commands and note that, 2431 | like in gdb and similar debuggers, you can also use their short forms: `c`, `q`, 2432 | `n`, `s`, `i`, and `f`. 2433 | 2434 | Apart from that those, you're free to use any Vim command, e.g. `:echo myvar`, 2435 | which gets executed in the context of the current position in the code. 2436 | 2437 | You basically get a 2438 | [REPL](https://en.wikipedia.org/wiki/Read%E2%80%93eval%E2%80%93print_loop) by 2439 | simply using `:debug 1`. 2440 | 2441 | It would be a pain if you had to single-step through every single line, so of 2442 | course we can define breakpoints, too. (Breakpoints are called breakpoints, 2443 | because the execution stops when they're hit, thus you can simply skip code 2444 | you're not interested in.) See `:h :breakadd`, `:h :breakdel`, and `:h 2445 | :breaklist` for further details. 2446 | 2447 | Let's assume you want to know what code is run every time you save a file: 2448 | 2449 | ```vim 2450 | :au BufWritePost 2451 | " signify BufWritePost 2452 | " * call sy#start() 2453 | :breakadd func *start 2454 | :w 2455 | " Breakpoint in "sy#start" line 1 2456 | " Entering Debug mode. Type "cont" to continue. 2457 | " function sy#start 2458 | " line 1: if g:signify_locked 2459 | >s 2460 | " function sy#start 2461 | " line 3: endif 2462 | > 2463 | " function sy#start 2464 | " line 5: let sy_path = resolve(expand('%:p')) 2465 | >q 2466 | :breakdel * 2467 | ``` 2468 | 2469 | As you can see, using `` will repeat the previous debugger command, `s` in 2470 | this case. 2471 | 2472 | `:debug` can be used in combination with the [verbose](#verbosity) option. 2473 | 2474 | ## Debugging syntax files 2475 | 2476 | Syntax files are often the cause for slowdowns due to wrong and/or complex 2477 | regular expressions. If the `+profile` [feature](#what-kind-of-vim-am-i-running) 2478 | is compiled in, Vim provides the super useful `:syntime` command. 2479 | 2480 | ```vim 2481 | :syntime on 2482 | " hit a few times to redraw the window which causes the syntax rules to get applied again 2483 | :syntime off 2484 | :syntime report 2485 | ``` 2486 | 2487 | The output contains important metrics. E.g. you can see which regexp takes too 2488 | long and should be optimized or which regexps are used all the time but never 2489 | even match. 2490 | 2491 | See `:h :syntime`. 2492 | 2493 | # Miscellaneous 2494 | 2495 | ## Additional resources 2496 | 2497 | | Resource | Description | 2498 | |----------|-------------| 2499 | | [Seven habits of effective text editing](http://www.moolenaar.net/habits.html) | By Bram Moolenaar, the author of Vim. | 2500 | | [Seven habits of effective text editing 2.0 (PDF)](http://www.moolenaar.net/habits_2007.pdf) | See above. | 2501 | | [IBM DeveloperWorks: Scripting the Vim editor](http://www.ibm.com/developerworks/views/linux/libraryview.jsp?sort_order=asc&sort_by=Title&search_by=scripting+the+vim+editor) | Five-part series on Vim scripting. | 2502 | | [Learn Vimscript the Hard Way](http://learnvimscriptthehardway.stevelosh.com) | Develop a Vim plugin from scratch. | 2503 | | [Practical Vim (2nd Edition)](https://pragprog.com/titles/dnvim2/practical-vim-second-edition) | Hands down the best book about Vim. | 2504 | | [Why, oh WHY, do those #?@! nutheads use vi?](http://www.viemu.com/a-why-vi-vim.html) | Common misconceptions explained. | 2505 | | [Your problem with Vim is that you don't grok vi](http://stackoverflow.com/a/1220118) | Concise, informative and correct. A real gem. | 2506 | 2507 | #### Screencasts 2508 | 2509 | - [vimcasts.org](http://vimcasts.org/episodes/archive) 2510 | - [By wincent](https://www.youtube.com/channel/UCXPHFM88IlFn68OmLwtPmZA) 2511 | - [By Derek Wyatt](http://derekwyatt.org/vim/tutorials/index.html) 2512 | 2513 | ## Vim distributions 2514 | 2515 | Vim distributions are bundles of custom settings and plugins for Vim. 2516 | 2517 | More advanced users know how to configure their editor anyway, so distributions 2518 | are mostly targeted at beginners. If you think about that, it's quite 2519 | paradoxical though: Making it easier by adding even more things to learn about? 2520 | 2521 | I know that many people don't want to spend hours and hours on customizing an 2522 | editor (and actually you never stop customizing your vimrc when you finally got 2523 | hooked), but eventually you only get efficient in Vim when you take the time to 2524 | learn it properly. 2525 | 2526 | Repeat after me: "A programmer should know their tools." 2527 | 2528 | Anyway, if you know what you're doing, you might draw some inspiration from 2529 | looking at a few distributions: 2530 | 2531 | - [cream](http://cream.sourceforge.net) 2532 | - [janus](https://github.com/carlhuda/janus.git) 2533 | - [spacevim](https://github.com/SpaceVim/SpaceVim) 2534 | - [spf13](https://github.com/spf13/spf13-vim) 2535 | 2536 | ## Standard plugins 2537 | 2538 | Many people are surprised by the fact that Vim comes with a handful of standard 2539 | plugins. Some get loaded by default (`:e $VIMRUNTIME/plugin`) and some are not 2540 | (`:e $VIMRUNTIME/pack/dist/opt`). Read `:h pack-add` on how to source the 2541 | latter. 2542 | 2543 | Most of the plugins that get loaded by default will never get used, though. 2544 | Disable them as you see fit. They will still be shown as sourced 2545 | (`:scriptnames`), but only the first lines actually get read before Vim bails 2546 | out. No further code (mappings, commands, logic) will be processed. 2547 | 2548 | | Plugin | Disable it using.. | Help | 2549 | |------------|-------------------------------------|------| 2550 | | 2html | `let g:loaded_2html_plugin = 1` | `:h 2html` | 2551 | | getscript | `let g:loaded_getscriptPlugin = 1` | `:h pi_getscript` | 2552 | | gzip | `let g:loaded_gzip = 1` | `:h pi_gzip` | 2553 | | logipat | `let g:loaded_logipat = 1` | `:h pi_logipat` | 2554 | | matchparen | `let g:loaded_matchparen = 1` | `:h pi_paren` | 2555 | | netrw | `let g:loaded_netrwPlugin = 1` | `:h pi_netrw` | 2556 | | rrhelper | `let g:loaded_rrhelper = 1` | `:e $VIMRUNTIME/plugin/rrhelper.vim` | 2557 | | spellfile | `let g:loaded_spellfile_plugin = 1` | `:h spellfile.vim` | 2558 | | tar | `let g:loaded_tarPlugin = 1` | `:h pi_tar` | 2559 | | vimball | `let g:loaded_vimballPlugin = 1` | `:h pi_vimball` | 2560 | | zip | `let g:loaded_zipPlugin = 1` | `:h pi_zip` | 2561 | 2562 | ## Map CapsLock to Control 2563 | 2564 | CapsLock belongs to the most useless keys on your keyboard, but it's much easier 2565 | to reach than the Control key, since it lies on your [home 2566 | row](https://raw.githubusercontent.com/mhinz/vim-galore/master/static/images/content-homerow.png). 2567 | Mapping CapsLock to Control is a great way to prevent or at least reduce 2568 | [RSI](https://de.wikipedia.org/wiki/Repetitive-Strain-Injury-Syndrom) if you 2569 | program a lot. 2570 | 2571 | Attention: When you get used to it, you can't live without it anymore. 2572 | 2573 | **macOS**: 2574 | 2575 | `System Preferences -> Keyboard -> Keyboard Tab -> Modifier Keys`. Change 2576 | "CapsLock" to "Control". 2577 | 2578 | **Linux**: 2579 | 2580 | To change the keys in X, put this in your `~/.xmodmap`: 2581 | 2582 | remove Lock = Caps_Lock 2583 | keysym Caps_Lock = Control_L 2584 | add Control = Control_L 2585 | 2586 | Afterwards source it via `$ xmodmap ~/.xmodmap`. 2587 | 2588 | An alternative would be using [caps2esc](https://github.com/oblitum/caps2esc) or 2589 | [xcape](https://github.com/alols/xcape). 2590 | 2591 | **Windows**: 2592 | 2593 | See [superuser.com: Map Caps-Lock to Control in Windows 2594 | 8.1](http://superuser.com/questions/764782/map-caps-lock-to-control-in-windows-8-1). 2595 | 2596 | ## Generating HTML from buffer 2597 | 2598 | Generate HTML from any buffer using `:TOhtml` from the 2html [standard 2599 | plugin](#standard-plugins). The output can be used for printing or easy web 2600 | publishing. 2601 | 2602 | The command creates a new buffer of the same name with `.html` appended. The 2603 | colors are the same as seen in Vim. They depend on the 2604 | [colorscheme](#colorschemes). 2605 | 2606 | The plugin knows several options to finetune the output, e.g. for setting the 2607 | encoding and font. 2608 | 2609 | See `:h :TOhtml`. 2610 | 2611 | ## Easter eggs 2612 | 2613 | | Command | Message | 2614 | |-----------|---------| 2615 | | `:Ni!` | `Do you demand a shrubbery?` | 2616 | | `:h 'sm'` | `NOTE: Use of the short form is rated PG.` | 2617 | | `:h 42` | `What is the meaning of life, the universe and everything? Douglas Adams, the only person who knew what this question really was about is now dead, unfortunately. So now you might wonder what the meaning of death is...` | 2618 | | `:h UserGettingBored` | `When the user presses the same key 42 times. Just kidding! :-)` | 2619 | | `:h bar` | `Ceci n'est pas une pipe.` | 2620 | | `:h holy-grail` | `You found it, Arthur!` | 2621 | | `:h map-modes` | `:nunmap can also be used outside of a monastery.` | 2622 | | `:help!` | `E478: Don't panic!` (Glitch? When used in a help buffer (`buftype=help`) this works like `:h help.txt` instead.) | 2623 | | `:smile` | Try it out yourself. ;-) Added in 7.4.1005. | 2624 | | `:hi!` | `Greetings, Vim user!` | 2625 | 2626 | ## Why hjkl for navigation? 2627 | 2628 | When [Bill Joy](https://en.wikipedia.org/wiki/Bill_Joy) created 2629 | [vi](https://en.wikipedia.org/wiki/Vi), a predecessor of Vim, he did it on a 2630 | [ADM-3A](https://en.wikipedia.org/wiki/ADM-3A) which had no extra cursor buttons 2631 | but used, you might already guessed it, hjkl instead. 2632 | 2633 | Keyboard layout: [click](https://raw.githubusercontent.com/mhinz/vim-galore/master/static/images/content-adm-3a-layout.jpg) 2634 | 2635 | This also shows why `~` is used to denote the home directory on Unix systems. 2636 | 2637 | # Common problems 2638 | 2639 | ## Editing small files is slow 2640 | 2641 | There are two things which can have a huge impact on performance: 2642 | 2643 | 1. Complex **regular expressions**. Particular the Ruby syntax file caused 2644 | people to have slowdowns in the past. (Also see [Debugging syntax files](#debugging-syntax-files).) 2645 | 2. **Screen redraws**. Some features force all lines to redraw. 2646 | 2647 | | Typical culprit | Why? | Solution? | 2648 | |-----------------|------|-----------| 2649 | | `:set cursorline` | Causes all lines to redraw. | `:set nocursorline` | 2650 | | `:set cursorcolumn` | Causes all lines to redraw. | `:set nocursorcolumn` | 2651 | | `:set relativenumber` | Causes all lines to redraw. | `:set norelativenumber` | 2652 | | `:set foldmethod=syntax` | If the syntax file is slow already, this makes it even worse. | `:set foldmethod=manual`, `:set foldmethod=marker` or [FastFold](https://github.com/Konfekt/FastFold) | 2653 | | `:set synmaxcol=3000` | Due to internal representation, Vim has problems with long lines in general. Highlights columns till column 3000. | `:set synmaxcol=200` | 2654 | | matchparen.vim | Loaded by default. Uses regular expressions to find the accompanying parenthesis. | Disable plugin: `:h matchparen` | 2655 | 2656 | **NOTE**: You only need to do this if you experience actual performance 2657 | drawbacks. In most cases using the things mentioned above is absolutely fine. 2658 | 2659 | ## Editing huge files is slow 2660 | 2661 | The biggest issue with big files is, that Vim reads the whole file at once. This 2662 | is done due to how buffers are represented internally. 2663 | ([Discussion on vim_dev@](https://groups.google.com/forum/#!topic/vim_dev/oY3i8rqYGD4/discussion)) 2664 | 2665 | If you only want to read, `tail hugefile | vim -` is a good workaround. 2666 | 2667 | If you can live without syntax, settings and plugins for the moment: 2668 | 2669 | ``` 2670 | $ vim -u NONE -N 2671 | ``` 2672 | 2673 | This should make navigation quite a lot faster, especially since no expensive 2674 | regular expressions for syntax highlighting are used. You should also tell Vim 2675 | not to use swapfiles and viminfo files to avoid long delays on writing: 2676 | 2677 | ``` 2678 | $ vim -n -u NONE -i NONE -N 2679 | ``` 2680 | 2681 | Putting it in a nutshell, try to avoid using Vim when intending to write really 2682 | huge files. :\ 2683 | 2684 | ## Bracketed paste (or why do I have to set 'paste' all the time?) 2685 | 2686 | Bracketed paste mode allows terminal emulators to distinguish between typed text 2687 | and pasted text. 2688 | 2689 | Did you ever tried pasting code into Vim and afterwards everything seemed messed 2690 | up? 2691 | 2692 | This only happens if you paste via `cmd+v`, `shift-insert`, `middle-click` etc. 2693 | because then you're just throwing text at the terminal emulator. Vim doesn't 2694 | know that you just pasted the text, it thinks you're an extremely fast typist. 2695 | Accordingly, it tries to indent the lines and fails. 2696 | 2697 | Obviously this is not an issue, if you paste using Vim's registers, e.g. `"+p`, 2698 | because then Vim knows that you're actually pasting. 2699 | 2700 | To workaround this, you have to `:set paste`, so it gets pasted as-is. See `:h 2701 | 'paste'` and `:h 'pastetoggle'`. 2702 | 2703 | If you're fed up with toggling `'paste'` all the time, have a look at this fine 2704 | plugin that does it for you: 2705 | [bracketed-paste](https://github.com/ConradIrwin/vim-bracketed-paste). 2706 | 2707 | Additional read from the same author as the plugin: 2708 | [here](http://cirw.in/blog/bracketed-paste). 2709 | 2710 | **Neovim**: Neovim tries to make all of this much more seamless and sets 2711 | bracketed paste mode automatically if the terminal emulator supports it. 2712 | 2713 | ## Delays when using escape key in terminal 2714 | 2715 | If you live in the command-line, you probably use a so-called _terminal 2716 | emulator_ like xterm, gnome-terminal, iTerm2, etc. (opposed to a real 2717 | [terminal](https://en.wikipedia.org/wiki/Computer_terminal)). 2718 | 2719 | Like their ancestors, terminal emulators use [escape 2720 | sequences](https://en.wikipedia.org/wiki/Escape_sequence) (or _control 2721 | sequences_) to control things like moving the cursor, changing text colors, etc. 2722 | They're simply strings of ASCII characters starting with an escape character 2723 | (displayed in [caret notation](https://en.wikipedia.org/wiki/Caret_notation) as 2724 | `^[`). When such a string arrives, the terminal emulator looks up the 2725 | accompanying action in the [terminfo](https://en.wikipedia.org/wiki/Terminfo) 2726 | database. 2727 | 2728 | To make the problem clearer, I'll explain mapping timeouts first. They always 2729 | happen when there's ambiguity between mappings: 2730 | 2731 | ```vim 2732 | :nnoremap ,a :echo 'foo' 2733 | :nnoremap ,ab :echo 'bar' 2734 | ``` 2735 | 2736 | Both mappings work as expected, but when typing `,a`, there will be a delay of 1 2737 | second, because Vim waits whether the user keys in another `b` or not. 2738 | 2739 | Escape sequences pose the same problem: 2740 | 2741 | - `` is used a lot for returning to normal mode or quitting an action. 2742 | - Cursor keys are encoded using escape sequences. 2743 | - Vim expects Alt (also called _Meta key_) to send a proper 8-bit 2744 | encoding with the high bit set, but many terminal emulators don't support it 2745 | (or don't enable it by default) and send an escape sequence instead. 2746 | 2747 | You can test the above like this: `vim -u NONE -N` and type `i` and 2748 | you'll see a sequence inserted that starts with `^[` which denotes the escape 2749 | character. 2750 | 2751 | Putting it in a nutshell, Vim has a hard time distinguishing between a typed 2752 | `` character and a proper escape sequence. 2753 | 2754 | By default, Vim uses `:set timeout timeoutlen=1000`, so it delays on ambiguity 2755 | of mappings _and_ key codes by 1 second. This is a sane value for mappings, but 2756 | you can define the key code timeout on its own which is the most common 2757 | workaround for this entire issue: 2758 | 2759 | ```vim 2760 | set timeout " for mappings 2761 | set timeoutlen=1000 " default value 2762 | set ttimeout " for key codes 2763 | set ttimeoutlen=10 " unnoticeable small value 2764 | ``` 2765 | 2766 | Under `:h ttimeout` you find a small table showing the relationship between 2767 | these options. 2768 | 2769 | If you're using tmux between Vim and your terminal emulator, also put this in 2770 | your `~/.tmux.conf`: 2771 | 2772 | ```tmux 2773 | set -sg escape-time 0 2774 | ``` 2775 | 2776 | ## Function search undo 2777 | 2778 | - A search pattern in a command (`/`, `:substitute`, ...) changes the "last used 2779 | search pattern". (It's saved in the `/` register; print it with `:echo @/`). 2780 | - A simple text change can be redone with `.`. (It's saved in the `.` register; 2781 | print it with `:echo @.`). 2782 | 2783 | Both things are _not_ the case, if you do them from a function, though! Thus you 2784 | can't easily highlight words from a function or redo the text changes made by 2785 | it. 2786 | 2787 | Help: `:h function-search-undo` 2788 | 2789 | # Technical quirks 2790 | 2791 | ## Newline used for NUL 2792 | 2793 | NUL characters (`\0`) in a file, are stored as newline (`\n`) in memory and 2794 | displayed in a buffer as `^@`. 2795 | 2796 | See `man 7 ascii` and `:h NL-used-for-Nul` for more information. 2797 | 2798 | # Terminology 2799 | 2800 | ## Vim script? Vimscript? VimL? 2801 | 2802 | `Vim script`, `Vimscript`, and `VimL` all refer to the same thing: The 2803 | programming language used for scripting Vim. Even though 2804 | [8.0.360](https://github.com/vim/vim/commit/b544f3c81f1e6a50322855681ac266ffaa8e313c) 2805 | changed all references from `VimL` to `Vim script`, which can now be considered 2806 | the official term, `VimL` is still widespread all over the internet. 2807 | 2808 | No matter which term you use, everyone will understand it. 2809 | -------------------------------------------------------------------------------- /static/images/badge-awesome.svg: -------------------------------------------------------------------------------- 1 | 2 | -------------------------------------------------------------------------------- /static/images/content-adm-3a-layout.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/mhinz/vim-galore/604f1a6f39705a83c02dd94b7ff2db1d3ff136f7/static/images/content-adm-3a-layout.jpg -------------------------------------------------------------------------------- /static/images/content-block_insert.gif: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/mhinz/vim-galore/604f1a6f39705a83c02dd94b7ff2db1d3ff136f7/static/images/content-block_insert.gif -------------------------------------------------------------------------------- /static/images/content-homerow.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/mhinz/vim-galore/604f1a6f39705a83c02dd94b7ff2db1d3ff136f7/static/images/content-homerow.png -------------------------------------------------------------------------------- /static/images/logo-vim-galore.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/mhinz/vim-galore/604f1a6f39705a83c02dd94b7ff2db1d3ff136f7/static/images/logo-vim-galore.png -------------------------------------------------------------------------------- /static/minimal-vimrc.vim: -------------------------------------------------------------------------------- 1 | " 2 | " A (not so) minimal vimrc. 3 | " 4 | 5 | " You want Vim, not vi. When Vim finds a vimrc, 'nocompatible' is set anyway. 6 | " We set it explicitely to make our position clear! 7 | set nocompatible 8 | 9 | filetype plugin indent on " Load plugins according to detected filetype. 10 | syntax on " Enable syntax highlighting. 11 | 12 | set autoindent " Indent according to previous line. 13 | set expandtab " Use spaces instead of tabs. 14 | set softtabstop =4 " Tab key indents by 4 spaces. 15 | set shiftwidth =4 " >> indents by 4 spaces. 16 | set shiftround " >> indents to next multiple of 'shiftwidth'. 17 | 18 | set backspace =indent,eol,start " Make backspace work as you would expect. 19 | set hidden " Switch between buffers without having to save first. 20 | set laststatus =2 " Always show statusline. 21 | set display =lastline " Show as much as possible of the last line. 22 | 23 | set showmode " Show current mode in command-line. 24 | set showcmd " Show already typed keys when more are expected. 25 | 26 | set incsearch " Highlight while searching with / or ?. 27 | set hlsearch " Keep matches highlighted. 28 | 29 | set ttyfast " Faster redrawing. 30 | set lazyredraw " Only redraw when necessary. 31 | 32 | set splitbelow " Open new windows below the current window. 33 | set splitright " Open new windows right of the current window. 34 | 35 | set cursorline " Find the current line quickly. 36 | set wrapscan " Searches wrap around end-of-file. 37 | set report =0 " Always report changed lines. 38 | set synmaxcol =200 " Only highlight the first 200 columns. 39 | 40 | set list " Show non-printable characters. 41 | if has('multi_byte') && &encoding ==# 'utf-8' 42 | let &listchars = 'tab:▸ ,extends:❯,precedes:❮,nbsp:±' 43 | else 44 | let &listchars = 'tab:> ,extends:>,precedes:<,nbsp:.' 45 | endif 46 | 47 | " The fish shell is not very compatible to other shells and unexpectedly 48 | " breaks things that use 'shell'. 49 | if &shell =~# 'fish$' 50 | set shell=/bin/bash 51 | endif 52 | 53 | " Put all temporary files under the same directory. 54 | " https://github.com/mhinz/vim-galore#temporary-files 55 | set backup 56 | set backupdir =$HOME/.vim/files/backup/ 57 | set backupext =-vimbackup 58 | set backupskip = 59 | set directory =$HOME/.vim/files/swap// 60 | set updatecount =100 61 | set undofile 62 | set undodir =$HOME/.vim/files/undo/ 63 | set viminfo ='100,n$HOME/.vim/files/info/viminfo 64 | --------------------------------------------------------------------------------