" ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ " Tom Ryder (tejr)’s Literate Vimrc " ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ " " Last updated: Thu, 04 Jul 2019 10:28:57 +0000 " " │ And I was lifted up in heart, and thought " │ Of all my late-shown prowess in the lists, " │ How my strong lance had beaten down the knights, " │ So many and famous names; and never yet " │ Had heaven appeared so blue, nor earth so green, " │ For all my blood danced in me, and I knew " │ That I should light upon the Holy Grail. " │ " │ —Tennyson " " This file is an attempt at something like a “literate vimrc”, in the " tradition of Donald Knuth’s “literate programming”: " " " The dotfiles project that comprises it is maintained here: " " " This is a long file, and comments abound within. Should this be bothersome, " one could execute this command in Vim itself to strip out all lines either " blank or comprising solely comments: " " :g/\m^$\|^\s*"/d " " This file should be saved as ‘vimrc’—no leading period—in the user runtime " directory. On Unix-like operating systems, hereinafter referred to as " “*nix”, that directory is ‘~/.vim’; on Windows, it’s ‘~/vimfiles’. " Fortunately, those are the only two kinds of operating systems that exist, " anywhere in the world. " " It requires Vim v7.0.0 or newer, with the +eval feature, and the " 'compatible' option turned off, chiefly to allow line continuations. The " vimrc stub at ~/.vimrc (Unix) or ~/_vimrc (Windows) should check that these " conditions are met before loading this file with ‘:runtime vimrc’. " " All of this should survive a pass of the Vim script linter Vint with no " errors, warnings, or style problems: " " We’ll begin by making sure that we and Vim are speaking the same language. " Since it’s been the future for a few years now, this file has characters " outside the ASCII character set, which prompts Vint to suggest declaring the " file encoding with a :scriptencoding command. The :help for that command " specifies that this should be done after 'encoding' is set, so we’ll do that " here, too. " " On *nix, I define the primary locale environment variable $LANG, almost " always specifying a multibyte locale. This informs Vim’s choice of internal " character encoding, but the default for the 'encoding' option in the absence " of a valid $LANG is ‘latin1’. Since this is almost never what I want, we’ll " manually choose the UTF-8 encoding for Unicode in the absence of any other " explicit specification. " if &encoding ==# 'latin1' && !exists('$LANG') set encoding=utf-8 endif scriptencoding utf-8 " With encoding handled, we’ll turn our attention to the value of the " 'runtimepath' option, since any scripts loaded from the paths specified " therein control so much of the behaviour of Vim. I’d like to do this as " accurately as possible, even with Vim’s unintuitive behavior around escaping " of these variables. One of the first things we’ll need to be able to do is " split the value of 'runtimepath' into its constituent path parts. " " Splitting the values of these comma-separated options correctly is " surprisingly complicated. The list separator for such options is more " accurately defined as follows: " " │ A comma not preceded by a backslash, and possibly followed by an arbitrary " │ number of spaces and commas. " " The pattern required for the split breaks down like this: " " \\ ← Literal backslash " \@ " function! s:Map(list, Func) abort return has('patch-7.4.1989') \ ? map(a:list, a:Func) \ : map(a:list, string(a:Func).'(0, v:val)') endfunction " We will need to be able to escape and unescape commas within separated list " items. As noted above, we do this by adding and removing a backslash before " each comma. " function! s:EscItem(item) abort return escape(a:item, ',') endfunction function! s:UnEscItem(key, val) abort return substitute(a:val, '\\,', ',', 'g') endfunction " We will need a way to escape a string for general use in an :execute wrapper " to prevent it being interpreted as anything but a string. The fnameescape() " function, while somewhat misnamed, is the correct way to do this, but it " wasn’t added until Vim v7.1.299, so we’ll have to do our best to backport it " here. " " " function! s:EscArg(arg) abort return exists('*fnameescape') \ ? fnameescape(a:arg) \ : escape(a:arg, "\n\r\t".' *?[{`$\%#''"|!<') endfunction " For the particular case of 'runtimepath', we also need to escape glob " characters like * to prevent them from being expanded. " function! s:EscWild(string) abort let string = a:string return escape(string, '\*?[{`''$~') endfunction " If an environment variable MYVIM exists, and it isn’t blank, apply its value " as the first value of 'runtimepath', after escaping it appropriately. " Otherwise, do it the other way around: the first path in the 'runtimepath' " list becomes MYVIM. " if exists('$MYVIM') && $MYVIM != '' execute 'set runtimepath^='.s:EscArg(s:EscItem(s:EscWild( \ $MYVIM \))) elseif &runtimepath != '' let $MYVIM = s:SplitOption(&runtimepath)[0] endif " We need a function to reliably create a full path, whether or not the " directories already exist. We create a wrapper with similar calling " conventions to mkdir(), but with the ‘p’ value for the second parameter " {prot} forced on. You can still provide alternative permissions in the " second argument. " function! s:CreatePath(name, ...) abort if isdirectory(a:name) return 1 endif let prot = a:0 >= 1 ? a:1 : 0755 return mkdir(a:name, 'p', prot) endfunction " That’s a useful function, too, so we make it available to the user with " a user command. We’ll generally use the function form, as it requires less " escaping. An optional second argument can be provided, corresponding to the " mkdir() permissions parameter. " command! -bar -complete=dir -nargs=1 CreatePath \ call s:CreatePath() " Now that we have a clean means to create directories if they don’t already " exist, let’s apply it for the first time to the user runtime directory. " Note that we aren’t checking whether this actually succeeded. We do want " errors raised if there were problems with the creation, but we’ll barrel on " ahead regardless after warning the user about our failure. " call s:CreatePath($MYVIM) " Our next application of our new :CreatePath command is to configure the path " for the viminfo metadata file, putting it in a cache subdirectory of the " user runtime directory set in MYVIM. " " Using this non-default location for viminfo has the nice benefit of " preventing command and search history from getting clobbered when something " runs Vim without using this vimrc, because such an instance will safely " write its history to the default viminfo path instead. It also contributes " to our aim of having everything related to the Vim runtime process in one " dedicated directory tree. " " The normal method of specifying the path to the viminfo file, as applied " here, is an addendum of the path to the 'viminfo' option with an "n" prefix. " Vim v8.1.716 introduced a nicer way to set this with an option named " 'viminfofile', but that’s still too new for us to use just yet. " " " let s:viminfo = $MYVIM.'/viminfo' execute 'set viminfo+='.s:EscArg('n'.s:viminfo) " Speaking of recorded data in viminfo files, the default Vim limit of a mere " 50 entries for command and search history is pretty stingy. Because I don’t " think I’m ever likely to be in a situation where remembering several " thousand Vim commands and search patterns is going to severely tax memory, " let alone disk space, I’d rather this limit were much higher. It’s " sometimes really handy to dig up commands from many days ago. " " The maximum value for the 'history' option is documented in ‘:help " 'history'’ as 10000, so let’s just use that, and see if anything breaks. " set history=10000 " We’ll now enable automatic backups of most file buffers, since that’s off by " default. In practice, I don’t need these backups very much, at least if I’m " using version control sensibly, but they have still saved my bacon a few " times. " " We’ll try to keep the backup files in a dedicated cache directory, to stop " them popping up next to the file to which they correspond, and getting " accidentally committed to version control. " " If Vim is new enough, we’ll add two trailing slashes to the path we’re " inserting, which prompts Vim to incorporate the full escaped path of the " relevant buffer in the backup filename, avoiding collisions. " " As a historical note, other similar directory path list options supported " this trailing slashes hint for a long time before 'backupdir' caught up to " them. The 'directory' option for swap files has supported it at least as " far back as v5.8.0 (2001), and 'undodir' appears to have supported it since " its creation in v7.2.438. Even though ‘:help 'backupdir'’ didn’t say so, " people assumed it would work the same way, when in fact Vim simply ignored " it until v8.1.0251. " " I don’t want to add the slashes to the option value in older versions of Vim " where they don’t do anything, so we’ll check the version ourselves to see if " there’s any point in including them. " " " " It’s all so awkward. Surely separate options named something like " 'backupfullname', 'swapfilefullname' would have been clearer. " set backup let s:backupdir = $MYVIM.'/backup' call s:CreatePath(s:backupdir, 0700) execute 'set backupdir^='.s:EscArg(s:EscItem( \ s:backupdir.(has('patch-8.1.251') ? '//' : ''), \)) " Files in certain directories on Unix-compatible filesystems should not be " backed up, for security reasons. This is particularly important if editing " temporary files created by sudoedit(8). On Unix-like systems, we here add " a few paths to the default value of 'backupskip' in order to prevent the " creation of such undesired backup files. " " * /dev/shm: RAM disk, default path for password-store’s temporary files " * /usr/tmp: Hard-coded path for sudoedit(8) [1/2] " * /var/tmp: Hard-coded path for sudoedit(8) [2/2] " " Prior to v8.1.1519, Vim didn’t check patterns added to 'backupskip' for " uniqueness, so adding the same path repeatedly resulted in duplicate strings " in the value. This was due to the absence of the P_NODUP flag for the " option’s definition in src/option.c in the Vim source code. If we’re using " a version older than v8.1.1519, we’ll need to explicitly reset 'backupskip' " to its default value before adding patterns to it, so that reloading this " file doesn’t stack up multiple copies of any added paths. " " " if has('unix') if !has('patch-8.1.1519') set backupskip& endif set backupskip^=/dev/shm/*,/usr/tmp/*,/var/tmp/* endif " Keep swap files for file buffers in a dedicated directory, rather than the " default of writing them to the same directory as the buffer file. Add two " trailing slashes to the path to prompt Vim to use the full escaped path in " its name, in order to avoid filename collisions, since the 'directory' " option has supported that hint for much longer than 'backupdir' has. We " apply CreatePath() to attempt to create the path first, if needed. " let s:directory = $MYVIM.'/swap' call s:CreatePath(s:directory, 0700) execute 'set directory^='.s:EscArg(s:EscItem( \ s:directory.'//' \)) " Keep tracked undo history for files permanently, in a dedicated cache " directory, so that the u/:undo and CTRL-R/:redo commands will work between " Vim invocations. " " The 'undodir' option has the same structure as 'backupdir' and 'directory'; " if we have a user runtime directory, create a sub-subdirectory within it " dedicated to the undo files cache. Note also the trailing double-slash as " a signal to Vim to use the full path of the original file in its undo file " cache’s name. " " Support for these persistent undo file caches was not released until v7.3.0, " so we need to check for the feature’s presence before we enable it. " if has('persistent_undo') set undofile let s:undodir = $MYVIM.'/undo' call s:CreatePath(s:undodir, 0700) execute 'set undodir^='.s:EscArg(s:EscItem( \ s:undodir.'//' \)) endif " Now that we have a bit more confidence in our runtime environment, set up " all of the filetype detection, plugin, and indent hooks. " filetype plugin indent on " There are a couple of contexts in which it's useful to reload filetypes for " the current buffer, quietly doing nothing if filetypes aren't enabled. " We'll set up a user command named :ReloadFileType to do this, with " a script-local function backing it. " function! s:ReloadFileType() abort if exists('g:did_load_filetypes') doautocmd filetypedetect BufRead endif endfunction command! -bar ReloadFileType \ call s:ReloadFileType() " We'll also define a :ReloadVimrc command. This may seem like overkill, at " first. Surely just `:source $MYVIMRC` would be good enough? " " The problem is there are potential side effects to the current buffer when " the vimrc is reloaded. The :set commands for options like 'expandtab' and " 'shiftwidth' may trample over different buffer-local settings that were " specified by filetype and indent plugins. To ensure these local values are " reinstated, we'll define the new command wrapper to issue a :ReloadFileType " command after the vimrc file is sourced. " " We can't put the actual :source command into the script-local function we " define here, because Vim would get upset that we're trying to redefine " a function as it executes! " " Just to be on the safe side, we also suppress any further ##SourceCmd hooks " from running the :source command with a :noautocmd wrapper. This is " a defensive measure to avoid infinite recursion. It may not actually be " necessary. " " We emit a message afterwards, just to make it clear that something has " happened. The :redraw just before that message seems to be necessary for " this message to display correctly. I'm not sure why. " function! s:ReloadVimrc() abort ReloadFileType redraw echomsg fnamemodify($MYVIMRC, ':p:~').' reloaded' endfunction command! -bar ReloadVimrc \ noautocmd source $MYVIMRC | call s:ReloadVimrc() " We'll now create or reset a group of automatic command hooks specific to " matters related to reloading the vimrc itself, or maintaining and managing " options set within it. " augroup vimrc autocmd! augroup END " Reload the stub vimrc, and thereby this main one, each time either of them " is written. This often makes errors in the file immediately apparent, and " saves restarting Vim or running the :source command manually, which I almost " always want to do after changing my vimrc file anyway. " autocmd vimrc BufWritePost $MYVIMRC,$MYVIM/vimrc \ ReloadVimrc " If Vim is new enough (v7.0.187) to support the ##SourceCmd event for " automatic command hooks, we'll also apply a hook for that event to catch " invocations of :source of either vimrc file, and translate that into " reloading the stub vimrc. " " " if exists('##SourceCmd') autocmd vimrc SourceCmd $MYVIMRC,$MYVIM/vimrc \ ReloadVimrc endif " For spelling, use New Zealand English by default, but later on we’ll " configure a leader mapping to switch to United States English, since I so " often have to write for Yankees. We’ll set the 'spellfile' option too, to " place it in the cache directory into which we’ve been putting everything. " We’ll follow Vim’s standard naming convention for the file itself, though. " If available, my plugin spellfile_local.vim will extend this later to add " more spelling word lists per filetype and per file. " " We briefly set 'isfname' to every character but NUL if we’re using Unix, " since Vim uses it internally for 'spellfile' assignment to decide whether " the path is valid. We put it back immediately afterwards. " set spelllang=en_nz let s:spelldir = $MYVIM.'/spell' call s:CreatePath(s:spelldir) let s:spellfile = s:spelldir.'/'.join([ \ split(&spelllang, '_')[0], \ &encoding, \ 'add', \], '.') if has('unix') let s:isfname = &isfname set isfname=1-255 endif execute 'set spellfile^='.s:EscArg(s:EscItem(s:spellfile)) let &isfname = s:isfname " Spell checking includes optional support for catching lower case letters at " the start of sentences, and defines a pattern in 'spellcapcheck' for the end " of a sentence. The default is pretty good, but with two-spacing with " 'cpoptions' including ‘J’ and 'formatoptions' including ‘p’ as set later in " this file, we can be less ambiguous in this pattern. We require two " consecutive spaces, a newline, a carriage return, or a tab to mark the end " of a sentence. This means that we could make abbreviations like "i.e. " something" without flagging "something" as a spelling error. " " We use :let syntax rather than :set here, just to avoid a whole bunch of " annoying escaping for the value. " let &spellcapcheck = '[.?!]\%( \|[\n\r\t]\)' " For word completion in insert mode with CTRL-X CTRL-K, or if 'complete' " includes the ‘k’ flag, the 'dictionary' option specifies the path to the " system word list. This makes the dictionary completion work consistently, " even if 'spell' isn’t set at the time to coax it into using 'spellfile'. " " It’s not an error if the system directory file added first doesn’t exist; " it’s just a common location that often yields a workable word list, and does " so on all of my main machines. " " At some point, I may end up having to set this option along with 'spellfile' " a bit more intelligently to ensure that spell checking and dictionary " function consistently, and with reference to the same resources. For the " moment, I’ve just added another entry referring to a directory in the user " runtime directory, but I don’t have anything distinct to put there yet. " " In much the same way, we add an expected path to a thesaurus, for completion " with CTRL-X CTRL-T in insert mode, or with ‘t’ added to 'completeopt'. The " thesaurus data isn’t installed as part of the default ‘install-vim’ target " in tejr’s dotfiles, but it can be retrieved and installed with " ‘install-vim-thesaurus’. " " I got the thesaurus itself from the link in the :help for 'thesaurus' in " v8.1. It’s from WordNet and MyThes-1. I maintain a mirror on my own " website that the Makefile recipe attempts to retrieve. I had to remove the " first two metadata lines from thesaurus.txt, as Vim appeared to interpret " them as part of the body data. " " Extra checks for appending the 'dictionary' and 'thesaurus' paths in MYVIM " need to be made, because the P_NDNAME property is assigned to them, which " enforces a character blacklist in the option value. We check for the " expected Vim error code here, and if the MYVIM path offends, we just skip " the setting entirely, rather than throwing cryptic errors at the user. None " of the blacklisted characters are particularly wise characters to have in " paths, anyway, legal though they may be on Unix filesystems. We can’t work " around this one with 'isfname'; the blacklist is hardcoded. " set dictionary^=/usr/share/dict/words let s:ref = $MYVIM.'/ref' try execute 'set dictionary^='.s:EscArg(s:EscItem( \ s:ref.'/dictionary.txt' \)) execute 'set thesaurus^='.s:EscArg(s:EscItem( \ s:ref.'/thesaurus.txt' \)) catch /^Vim\%((\a\+)\)\=:E474:/ endtry " Next, we’ll modernize a little in adjusting some options with old " language-specific defaults. " " Traditional vi was often used for development in the C programming language. " The default values for a lot of Vim’s options still reflect this common use " pattern. In this case, the 'comments' and 'commentstring' options reflect " the C syntax for comments: " " /* " * This is an ANSI C comment. " */ " " Similarly, the 'define' and 'include' options default to C preprocessor " directives: " " #define FOO "bar" " " #include "baz.h" " " Times change, however, and I don’t get to work with C nearly as much as I’d " like. The defaults for these options no longer make sense, and so we blank " them, compelling filetype plugins to set them as they need instead. " " The default value for the 'path' option is similar, in that it has an aged " default; this option specifies directories in which project files and " includes can be unearthed by navigation commands like 'gf'. Specifically, " its default value comprises /usr/include, which is another C default. Let’s " get rid of that, too. " set comments= commentstring= define= include= set path-=/usr/include " Next, we’ll adjust the global indentation settings. In general and as " a default, I prefer spaces to tabs, and I like to use four of them, for " a more distinct visual structure. Should you happen to disagree with this, " I cordially invite you to fite me irl. " " " " Filetype indent plugins will often refine these settings for individual " buffers. For example, 'expandtab' is not appropriate for Makefiles, nor for " the Go programming language. For another, two-space indents are more " traditional for Vim script. " set autoindent set expandtab set shiftwidth=4 set smarttab " Apply 'softtabstop' option to make a tab key press in insert mode insert the " same number of spaces as defined by the indent depth in 'shiftwidth'. If " Vim is new enough to support it (v7.3.693), apply a negative value to do " this dynamically if 'shiftwidth' changes. " " " if v:version > 703 || v:version == 703 && has('patch693') set softtabstop=-1 else let &softtabstop = &shiftwidth endif " Relax traditional vi’s harsh standards over what regions of the buffer can " be removed with backspace in insert mode. While this admittedly allows bad " habits to continue, since insert mode by definition is not really intended " for deleting text, I feel the convenience outweighs that in this case. " set backspace+=eol " Line breaks set backspace+=indent " Leading whitespace characters created by 'autoindent' set backspace+=start " Text before the start of the current insertion " When soft-wrapping text with the 'wrap' option on, which is off by default, " break the lines between words, rather than within them; it’s much easier to " read. " set linebreak " Similarly, show that the screen line is a trailing part of a wrapped line by " prefixing it with an ellipsis. If we have a multi-byte encoding, use " a proper ellipsis character to save a couple of columns, but otherwise three " periods will do just fine. " " … U+2026 HORIZONTAL ELLIPSIS " " Note that we test for the presence of a multi-byte encoding with a special " feature from ‘:help feature-list’, as recommended by ‘:help encoding’. " Checking that ‘&encoding ==# 'utf-8'’ is not quite the same thing, though " it’s unlikely I’ll ever use a different Unicode encoding by choice. " if has('multi_byte_encoding') set showbreak=… else set showbreak=... endif " The visual structure of code provided by indents breaks down if a lot of the " lines wrap. Ideally, most if not all lines would be kept below 80 " characters, but in cases where this isn’t possible, soft-wrapping longer " lines when 'wrap' is on so that the indent is preserved in the following " line mitigates this breakdown somewhat. " " With this 'breakindent' option set, it’s particularly important to have " 'showbreak' set to something besides an empty string, as done above, " otherwise without line numbers it’s hard to tell what’s a logical line and " what’s not. " " The 'breakindent' option wasn’t added until v7.4.338, so we need to check it " exists before we set it. " " " if exists('+breakindent') set breakindent endif " Rather than rejecting operations like :write or :saveas when 'readonly' is " set or in other situations in which data might be lost, Vim should give me " a prompt to allow me to confirm that I know what I’m doing. " set confirm " If Vim receives an Escape key code in insert mode, it shouldn’t wait to see " if it’s going to be followed by another key code, despite this being how the " function keys and Meta/Alt modifier are implemented for many terminal types. " Otherwise, if I press Escape, there’s an annoying delay before 'showmode' " stops showing '--INSERT--'. " " This breaks the function keys and the Meta/Alt modifier in insert mode in " most or maybe all of the terminals I use, but I don’t want those keys in " insert mode, anyway. All of this works fine in the GUI, of course. " set noesckeys " Automatic text wrapping options using flags in the 'formatoptions' option " begin here. I rely on the filetype plugins to set the ‘t’ and ‘c’ flags for " this option to configure whether text or comments should be wrapped, as " appropriate for the document type or language, and so I don’t mess with " either of those flags here. " If a line is already longer than 'textwidth' would otherwise limit when " editing of that line begins in insert mode, don’t suddenly automatically " wrap it; I’ll break it apart myself with a command like 'gq'. This doesn’t " seem to stop paragraph reformatting with ‘a’, if that’s set. " set formatoptions+=l " Don’t wrap a line in such a way that a single-letter word like "I" or "a" is " at the end of it. Typographically, as far as I can tell, this seems to be " a stylistic preference rather than a rule, rather like avoiding "widow" and " "orphan" lines in typesetting. I think it generally looks better to have " the short word start the line, so we’ll switch it on. " set formatoptions+=1 " If the filetype plugins have correctly described what the comment syntax for " the buffer’s language looks like, it makes sense to use that to figure out " how to join lines within comments without redundant comment syntax cropping " up. For example, with this set, joining lines in this very comment with ‘J’ " would remove the leading ‘"’ characters. " " This 'formatoptions' flag wasn’t added until v7.3.541. Because we can’t " test for the availability of option flags directly, we resort to a version " number check before attempting to set it. I don’t like using :silent! to " suppress errors for this sort of thing when I can reasonably avoid it, even " if the tests are somewhat more verbose. " " " if v:version > 703 || v:version == 703 && has('patch541') set formatoptions+=j endif " A momentary digression here into the doldrums of 'cpoptions'—after staunchly " opposing it for years, I have converted to two-spacing. You can blame Steve " Losh: " " " " Consequently, we specify that sentence objects for the purposes of the ‘s’ " text object, the ‘(’ and ‘)’ sentence motions, and formatting with the 'gq' " command must be separated by *two* spaces. One space does not suffice. " " My defection to the two-spacers is also the reason I now leave 'joinspaces' " set, per its default, so that two spaces are inserted when consecutive " sentences separated by a line break are joined onto one line by the ‘J’ " command. " set cpoptions+=J " Separating sentences with two spaces has an advantage in making a clear " distinction between two different types of periods: periods that abbreviate " longer words, as in “Mr. Moolenaar”, and periods that terminate sentences, " like this one. " " If we’re using two-period spacing for sentences, Vim can interpret the " different spacing to distinguish between the two types, and can thereby " avoid breaking a line just after an abbreviating period. For example, the " two words in “Mr. Moolenaar” should never be split apart, preventing " confusion on the reader’s part lest the word "Mr." look too much like the " end of a sentence, and also preserving the semantics of that same period for " subsequent reformatting; its single-space won’t get lost. " " So, getting back to our 'formatoptions' settings, that is what the ‘p’ flag " does. I wrote the patch that added it, after becoming envious of an " analogous feature during an ill-fated foray into GNU Emacs usage. " " " if has('patch-8.1.728') set formatoptions+=p endif " In an effort to avoid loading unnecessary files, we add a flag to the " 'guioptions' option to prevent the menu.vim runtime file from being loaded. " It doesn’t do any harm, but I never use it, and it’s easy to turn it off. " " The documentation for this flag in ‘:help 'go-M'’ includes a note saying the " flag should be set here, rather that in the GUI-specific gvimrc file, as one " might otherwise think. " if has('gui_running') set guioptions+=M endif " By default, Vim doesn’t allow a file buffer to have unwritten changes if " it’s not displayed in a window. Setting this option removes that " restriction so that buffers can remain in a modified state while not " actually displayed anywhere. " " This option is set in almost every vimrc I read; it’s so pervasive that " I sometimes see comments expressing astonishment or annoyance that it isn’t " set by default. However, I didn’t actually need this option for several " years of Vim usage, because I instinctively close windows onto buffers only " after the buffers within them have been written anyway. " " However, the option really is required for batch operations performed with " commands like :argdo or :bufdo, because Vim won’t otherwise tolerate " unwritten changes to a litany of buffers that are not displayed in any " window. After I started using such command maps a bit more often, " I realized I finally had a reason to turn this on permanently. " set hidden " Highlight matches for completed searches in the buffer text, but clear that " highlighting away when this vimrc file is reloaded. Later on in this file, " CTRL-L in normal mode is remapped to issue :nohlsearch in addition to its " usual screen refresh function. " set hlsearch nohlsearch " Highlight search matches in my text while I’m still typing my pattern, " including scrolling the screen to show the first such match if necessary. " This can be somewhat jarring, particularly when the cursor ends up scrolling " a long way from home in a large file, but I think the benefits of being able " to see instances of what I’m trying to match as I type the pattern do " outweigh that discomfort. " set incsearch " Don’t waste cycles and bandwidth redrawing the screen during execution of " macro recordings and scripts. " set lazyredraw " Define meta-characters to show in place of characters that are otherwise " invisible, or line wrapping attributes when the 'list' option is enabled. " " These 'list' characters all correspond to invisible or indistinguishable " characters. We leave the default eol:$ in place to show newlines, and add " a few more. " set listchars+=tab:>- " Tab characters, preserve width with hyphens set listchars+=trail:- " Trailing spaces set listchars+=nbsp:+ " Non-breaking spaces " The next pair of 'list' characters are arguably somewhat misplaced, in that " they don’t really represent invisible characters in the same way as the " others, but are hints for the presence of other characters on unwrapped " lines that are wider than the screen. They’re very useful, though. " " If the current encoding supports it, use these non-ASCII characters for the " markers, as they’re visually distinctive: " " extends: Signals presence of unwrapped text to screen right " » U+00BB RIGHT-POINTING DOUBLE ANGLE QUOTATION MARK " precedes: Signals presence of unwrapped text to screen left " « U+00BB LEFT-POINTING DOUBLE ANGLE QUOTATION MARK " " Failing that, ‘<’ and ‘>’ will do the trick. " if has('multi_byte_encoding') set listchars+=extends:»,precedes:« else set listchars+=extends:>,precedes:< endif " Don’t let your editor’s options be configured by content in arbitrary files! " Down with modelines! Purge them from your files! Écrasez l’infâme! " " I think that modelines are Vim’s worst misfeature, and that 'nomodeline' " should be the default. It’s enabled pretty bad security vulnerabilities " over the years, and it’s a lot more effective to use filetype detection, " other automatic command hooks, or methods like .editorconfig to set " variables specifically for a buffer or project. " set nomodeline " The only octal numbers I can think of that I ever even encounter are Unix " permissions masks, and I’d never use CTRL-A or CTRL-X to increment them. " Numbers with leading zeroes are far more likely to be decimals. " set nrformats-=octal " I like to leave the last line of the screen blank unless something is " actually happening in the editor for it to report, so I have grown to like " the Vim default of 'noruler'. CTRL-G shows me everything I need to know, " and is near-instinctive now. " " Rude system vimrc files tend to switch this back on, though, so we force it " off here. " set noruler " Sessions preserve window, tab, and buffer layout, and are thereby great for " more complex and longer-term projects like books, but they don’t play " together well with plugins and filetype plugins. Restoring the same " settings from both reloaded plugins and from the session causes screeds of " errors. Adjusting session behavior to stop it trying to restore the sorts " of settings that plugins manage makes them usable again. " set sessionoptions-=localoptions " No buffer options or mappings set sessionoptions-=options " No global options or mappings " Turn 'showcmd' off if a system vimrc has been rude enough to set it; I don’t " like how it can interfere with the display of longer lines. " set noshowcmd " The ‘I’ flag for the 'shortmess' option prevents the display of the Vim " startup screen with version information, :help hints, and donation " suggestion. After I registered Vim and donated to Uganda per the screen’s " plea, I didn’t feel bad about turning this off anymore. Even with this " setting in place, I wouldn’t normally see it too often anyway, as I seldom " start Vim with no file arguments. " " I haven’t felt the need to mess with the other flags in this option. " I don’t have any problems with spurious Enter prompts, which seems to be the " main reason people pile it full of letters. " set shortmess+=I " We declare a function just to make a slightly more readable way to express " a check that plugins are going to be loaded and that a plugin of a given " name appears to be available somewhere in one of the runtime paths. " function! s:PluginReady(name) abort return &loadplugins \ && globpath(&runtimepath, 'plugin/'.a:name.'.vim') != '' endfunction " We’ll only use the old 'showmatch' method of a brief jump to the matching " bracket under the cursor if the much-preferred matchparen.vim standard " plugin doesn’t look like it’s going to load, whether because plugins have " been disabled, or it’s not in any of the plugin directories. " if !s:PluginReady('matchparen') set showmatch matchtime=3 endif " I find the defaults of new windows opening above or to the left of the " previous window too jarring, because I’m used to both the i3 window manager " and the tmux terminal multiplexer doing it the other way around, in reading " order. I prefer the visual effect of the previous text staying where it is, " and the new window occupying previously blank space. " set splitbelow splitright " Limit the number of characters per line that syntax highlighting will " attempt to match. This is as much an effort to encourage me to break long " lines and do hard wrapping correctly as it is for efficiency. " set synmaxcol=500 " Vim has an internal list of terminal types that support using smoother " terminal redrawing, and for which 'ttyfast' is normally set, described in " ‘:help 'ttyfast'’. That list includes most of the terminals I use, but " there are a couple more for which the 'ttyfast' option should apply: the " windows terminal emulator PuTTY, and the terminal multiplexer tmux, both of " which I use heavily. " if &term =~# '^putty\|^tmux' set ttyfast endif " We really don’t want a mouse; while I use it a lot for cut and paste in X, " it just gets in the way if the tool running in the terminal tries to use it " too. Mouse events should be exclusively handled by the terminal emulator " application, so Vim shouldn’t try to give me terminal mouse support, even if " it would work. " " The manual suggests that disabling this should be done by clearing 't_RV', " but that didn’t actually seem to work when I tried it. " set ttymouse= " While using virtual block mode, allow me to navigate to any column of the " buffer window; don’t confine the boundaries of the block to the coordinates " of characters that actually exist in the buffer text. While working with " formatted columnar data with this off is generally OK, it’s a hassle for " more subtle applications of visual block mode. " set virtualedit+=block " I can’t recall a time that Vim’s error beeping or flashing was actually " useful to me, and so we turn it off in the manner that the manual instructs " in ‘:help 'visualbell'’. This enables visual rather than audio error bells, " but in the same breath, blanks the terminal attribute that would be used to " trigger such screen blinking, indirectly disabling the bell altogether. " " I thought at first that the newer 'belloff' and/or 'errorbells' options " would be a more intuitive way to keep Vim quiet, but the last time I checked " that, neither appeared to work as comprehensively as this older method does. " " Interestingly, the :help says that this setting has to be repeated in the " gvimrc file for GUI Vim. " set visualbell t_vb= " When Ex command line completion is started with Tab, list valid completions " and complete the command line to the longest common substring, just as Bash " does, with just the one key press. " " The default value of 'full' for the 'wildmode' option puts the full " completion onto the line immediately, which I tolerate for insert mode " completion but don’t really like on the Ex command line. Instead, I arrange " for that to happen only with a second key press. " set wildmenu set wildmode=list:longest,full " Define a list of patterns to ignore for file and directory command line " completion. Files and directories with names matching any of these patterns " won’t be presented as candidates for tab completion on the command line. " " To make this list, I went right through my home directory with " a ‘find’-toothed comb; counted the occurrences of every extension, forced " down to lowercase; and then manually selected the ones that I was confident " would seldom contain plain text. " " The following incantation does the trick with POSIX-compatible shell tools, " giving patterns for the top 100 alphanumeric extensions for files from the " running user’s home directory: " " $ (LC_ALL=C find "$HOME" ! -type d -name '*.?*' -exec \ " sh -c 'for fn ; do " ext=${fn##*.} " case $ext in " (*[![:alnum:]]*) continue ;; " (?*) printf "%s\n" "$ext" ;; " esac " done' _ {} + | " tr '[[:upper:]]' '[[:lower:]]' | sort | uniq -c | " sort -k1,1nr | awk 'NR <= 100 {print "*." $2}') " " I turned out to have rather a lot of .html and .vim files. " " If you’re scoffing at that and thinking "I could write a much simpler one", " please do so, and send it to me at to have yours put " in here instead, with appropriate credit. Don’t forget to handle more than " ARG_MAX files, include filenames with newlines, and that the -z or -0 null " separator extensions are not standardized in POSIX. " " " set wildignore=*~,#*# \,*.7z \,.DS_Store \,.git \,.hg \,.svn \,*.a \,*.adf \,*.asc \,*.au \,*.aup \,*.avi \,*.bin \,*.bmp \,*.bz2 \,*.class \,*.db \,*.dbm \,*.djvu \,*.docx \,*.exe \,*.filepart \,*.flac \,*.gd2 \,*.gif \,*.gifv \,*.gmo \,*.gpg \,*.gz \,*.hdf \,*.ico \,*.iso \,*.jar \,*.jpeg \,*.jpg \,*.m4a \,*.mid \,*.mp3 \,*.mp4 \,*.o \,*.odp \,*.ods \,*.odt \,*.ogg \,*.ogv \,*.opus \,*.pbm \,*.pdf \,*.png \,*.ppt \,*.psd \,*.pyc \,*.rar \,*.rm \,*.s3m \,*.sdbm \,*.sqlite \,*.swf \,*.swp \,*.tar \,*.tga \,*.ttf \,*.wav \,*.webm \,*.xbm \,*.xcf \,*.xls \,*.xlsx \,*.xpm \,*.xz \,*.zip " Allow me to be lazy and type a path to complete on the Ex command line in " all-lowercase, and transform the consequent completion to match the " appropriate case, like the Readline setting completion-ignore-case can be " used for GNU Bash. " " As far as I can tell, despite its name, the 'wildignore' case option doesn’t " have anything to do with the 'wildignore' option, and so files that would " match any of those patterns only with case insensitivity implied will still " be candidates for completion. " " The option wasn’t added until v7.3.72, so we need to check it exists before " we try to set it. " " " if exists('+wildignorecase') set wildignorecase endif " Enable syntax highlighting, but only if it’s not already on, to save " reloading the syntax files unnecessarily. " " " " For several months in 2018, as an experiment, I tried using terminals with " no color at all, imitating a phenomenally productive BSD purist co-worker " who abhorred color in any form on his terminals. He only drank black " coffee, too. If you’re reading this: Hello, bdh! " " That experiment was instructive and interesting, and I found I had been " leaning on color information in some surprising ways. However, some months " later, I found I still missed my colors, and so I went back to my " Kodachrome roots, and didn’t pine at all for that monochrome world. " " The thing I most like about syntax highlighting is detecting runaway " strings, which generally works in even the most threadbare language syntax " highlighting definitions. I kept missing such errors when I didn’t have the " colors. I don’t have high standards for it otherwise, except maybe for " shell script. " if !exists('syntax_on') syntax enable endif " Before we attempt to pick a syntax highlighting color scheme, we’ll set up " a couple of hooks for color scheme loading. In this case, we turn " 'cursorline' on if my 'sahara' color scheme is loaded, since I’ve configured " it to be a very dark gray that doesn’t stand out too much against a black " background. For any other color scheme, turn the option off, because it " almost always stands out too much for my liking. " " You’d think the pattern here could be used to match the color scheme name, " and it can be...after patch v7.4.108, when Christian Brabandt fixed it. " Until that version, it matched against the current buffer name, so we’re " forced to have an explicit test in the command instead. " " " autocmd vimrc ColorScheme * \ let &cursorline = g:colors_name ==# 'sahara' " Use 'dark' as my default value for 'background', in the absence of an " environment variable COLORFGBG or a response in v:termrbgresp that would set " it specifically. " if !exists('$COLORFGBG') && get(v:, 'termrbgresp', '') ==# '' set background=dark endif " If the background seems to be dark, and I have either the GUI or a 256 color " terminal, and my custom sahara.vim color scheme looks to be available, load " it. " if &background ==# 'dark' \ && (has('gui_running') || &t_Co >= 256) \ && globpath(&runtimepath, 'colors/sahara.vim') !=# '' colorscheme sahara endif " My mapping definitions begin here. I have some general personal rules for " approaches to mappings: " " * Use the configured Leader key as a prefix for mappings as much as " possible. " " * Use only the configured LocalLeader key as a prefix for mappings that are " defined as local to a buffer, which for me are almost always based on " &filetype and set up by ftplugin files. " " * If a normal mode map would make sense in visual mode, take the time to " configure that too. Use :xmap and its analogues rather than :vmap to " avoid defining unusable select-mode mappings, even though I never actually " use selection mode directly. " " * Avoid mapping in insert mode; let characters be literal to the greatest " extent possible, and avoid "doing more" in insert mode besides merely " inserting text as it’s typed. " " * Avoid key chords with Ctrl in favor of leader keys. " " * Never use Alt/Meta key chords; the terminal support for them is just too " confusing and flaky. " " * Don’t suppress display of mapped commands for no reason; it’s OK to show " the user the command that’s being run under the hood. Do avoid HIT-ENTER " prompts, though. " " * Avoid shadowing any of Vim’s existing functionality. If possible, extend " or supplement what Vim does, rather than replacing it. " " We’ll start with the non-leader mappings. Ideally, there shouldn’t be too " many of these. " " Use backspace as an even quicker way to switch to the current buffer’s " alternate buffer. User nickspoons of #vim was incredulous that I had never " used CTRL-^ and indeed did not know about it. I have since repented. " nnoremap " I find the space bar’s default behavior in normal mode of moving right one " character to be useless. Instead, I remap it to be a lazy way of paging " through the argument list buffers, scrolling a page until the last line of " the buffer is visible, and then moving to the :next buffer. " " I always wanted you to go into space, man. " nnoremap \ line('w$') < line('$') \ ? "\" \ : ":\next\" " I hate CTRL-C’s default insert mode behavior. It ends the insert session " without firing the InsertLeave event for automatic command hooks. Why would " anyone want that? It breaks plugins that hinge on mirrored functionality " between the InsertEnter and InsertLeave events, and doesn’t otherwise differ " from Escape or :stopinsert. Even worse, people think it’s a *synonym* for " Escape, and use it because it’s easier to reach than the Escape key or " CTRL-[. Terrible! " " Instead, I apply a custom plugin named insert_cancel.vim to make it cancel " the current insert operation; that is, if the buffer has changed at all " since the start of the insert operation, pressing CTRL-C will reverse it, " while ending insert mode and firing InsertLeave as normal. This makes way " more sense to me, and I use it all the time now. " " " " You might think on a first look, as I did, that a plugin is overkill, and " that a mapping like this would be all that’s required: " " :inoremap u " " Indeed, it *mostly* works, but there are some subtle problems with it. The " primary issue is that if you didn’t make any changes during the insert mode " session that you’re terminating, it *still* reverses the previous change, " which will be something else entirely that you probably *didn’t* mean to be " undone. The plugin’s way of working around this and the other shortcomings " of the simple mapping above is not too much more complicated, but it was not " easy to figure out. " " At any rate, we only want to establish the mapping if we can expect the " plugin to load, so test that 'loadplugins' is set and that the plugin file " exists with the expected filename. " " If the plugin isn’t available, I just abandon CTRL-C to continue its " uselessness. " if s:PluginReady('insert_cancel') imap (InsertCancel) endif " I often can’t remember (or guess) digraph codes, and want to look up how to " compose a specific character that I can name, at least in part. The table " in ‘:help digraph-table’ is what to use for that situation, and it solves " the problem, but I didn’t like the overhead of repeated lookups therein. " " Steve Losh has a solution I liked where a double-tap of CTRL-K in insert " mode brought up the applicable :help window: " " " " I took that one step further with a custom plugin named digraph_search.vim. " It parses the digraph table from :help and runs a simple text search of its " names using a string provided by the user. For example, searching for ACUTE " yields: " " > Digraphs matching ACUTE: " > ´ '' ACUTE ACCENT " > Á A' LATIN CAPITAL LETTER A WITH ACUTE " > É E' LATIN CAPITAL LETTER E WITH ACUTE " > Í I' LATIN CAPITAL LETTER I WITH ACUTE " > ...etc... " " " " This leaves you in insert mode, ready to hit CTRL-K one more time and then " type the digraph that you’ve hopefully found. " " Since a double-tap of CTRL-K does nothing in default Vim, we don’t bother " checking that the plugin’s available before we map to it; it’ll just quietly " do nothing. " imap (DigraphSearch) " I end up hitting CTRL-L to clear or redraw the screen in interactive shells " and tools like Mutt and Vim pretty often. It feels natural to me to stack " issuing a :nohlsearch command to stop highlighting searches on top of this. " " This gets by far the most use in normal mode, but I’d like it to work in " insert and visual modes, too, where it’s occasionally useful, especially on " things like mobile phone terminal emulators that can be choppy and require " a lot of redrawing. " " For each of these, we end the mapping with a CTRL-L in normal mode, thereby " extending rather than replacing Vim’s normal behavior. " nnoremap \ :nohlsearch " The insert mode wrapper for normal CTRL-L uses i_CTRL-O to issue a single " normal mode command. We intentionally use ‘:normal’ rather than ‘:normal!’ " so that the mapping works recursively. I tried using with :imap " for this, but it didn’t work. Maybe i_CTRL-O doesn’t respect mappings. " I couldn’t find any documentation about it. " inoremap :execute "normal \" " We use :vnoremap here rather than :xnoremap and thereby make the mapping " apply to select mode as well, because CTRL-L doesn’t reflect a printable " character, and so we may as well make it work, even though I don’t actually " use select mode directly. " vmap gv " By default, the very-useful normal mode command ‘&’ that repeats the " previous :substitute command doesn’t preserve the flags from that " substitution. I’d prefer it to do so, like the :&& command does, and it’s " easily remapped for both normal and visual mode, so let’s just do it. " noremap & \ :&& ounmap & sunmap & " I really like using the ‘!’ command in normal mode as an operator to filter " text through a shell command. It always bugged me a little that there " didn’t seem to be an analogue for a motion to filter text through an " internal command like :sort, so I wrote one. " " " nmap g: (ColonOperator) " I used Tim Pope’s unimpaired.vim plugin for ages, and I liked some of these " bracket pair mappings, so I’ve carried a few of the simpler ones over. All " of these can be prefixed with a count if needed, too. I use all of them " pretty regularly, even though cycling through lists to look for something " can be a bit wasteful. " Argument list nnoremap [a \ :previous nnoremap ]a \ :next " Buffers nnoremap [b \ :bprevious nnoremap ]b \ :bnext " Quickfix list nnoremap [c \ :cprevious nnoremap ]c \ :cnext " Location list nnoremap [l \ :lprevious nnoremap ]l \ :lnext " Here’s another mapping I particularly liked from unimpaired.vim; insert " blank lines from normal mode, using a custom plugin of mine called " put_blank_lines.vim. These use operator functions so that they’re " repeatable without repeat.vim. They accept count prefixes, too. " " " nmap [ (PutBlankLinesAbove) nmap ] (PutBlankLinesBelow) " We’re on to the leader maps, now. It’s difficult to know in what order to " describe and specify these. I used to have them in alphabetical order, but " it seems much more useful to group them by the type of action they take. " " First of all, let’s set the leader keys; backslash happens to be the " default, but I like to make my choice explicit here. As of 2019, I’m still " not certain that comma is the best choice for my local leader. I use it all " the time for this purpose, and it works well, but I don’t much like that it " shadows a useful function in the fFtT;, group, and I sometimes wonder if " I would use the key for its original function more, had I not shadowed it. " let mapleader = '\' let maplocalleader = ',' " If the local leader is a comma, map double-tap comma to its original " function in the relevant modes so that I can still use it quickly without " relying on mapping 'timeout'. " if maplocalleader ==# ',' noremap ,, , sunmap ,, endif " Let’s start with some simple ones; these ones all just toggle a boolean " option, and print its new value. They’re dirt simple to specify, and don’t " require any plugins. " " These are sometimes applicable in visual mode, and sometimes not. We’ll " start with the ones that only make sense as normal mode maps. Annoyingly, " a visual mode mapping for 'cursorline' toggling doesn’t work at all; " 'cursorline' is always off when in any visual mode, including block mode, " where it actually might have been really handy. "" Leader,TAB toggles automatic indentation based on the previous line nnoremap \ :set autoindent! autoindent? "" Leader,c toggles highlighted cursor row; doesn’t work in visual mode nnoremap c \ :set cursorline! cursorline? "" Leader,h toggles highlighting search results nnoremap h \ :set hlsearch! hlsearch? "" Leader,i toggles showing matches as I enter my pattern nnoremap i \ :set incsearch! incsearch? "" Leader,s toggles spell checking nnoremap s \ :set spell! spell? " The next group of option-toggling maps are much the same as the previous " group, except they also include analogous maps for visual mode, defined as " recursive maps into normal mode that conclude with re-selecting the text. "" Leader,C toggles highlighted cursor column; works in visual mode noremap C \ :set cursorcolumn! cursorcolumn? ounmap C sunmap C "" Leader,l toggles showing tab, end-of-line, and trailing white space noremap l \ :set list! list? ounmap l sunmap l "" Leader,n toggles line number display noremap n \ :set number! number? ounmap n sunmap n "" Leader,N toggles position display in bottom right noremap N \ :set ruler! ruler? ounmap N sunmap N "" Leader,w toggles soft wrapping noremap w \ :set wrap! wrap? ounmap w sunmap w " This next one just shows option state of the 'formatoptions' affecting how " text is automatically formatted; it doesn’t change its value. "" Leader,f shows the current 'formatoptions' at a glance nnoremap f \ :set formatoptions? " I often have to switch between US English and NZ English. The latter is " almost exactly the same as UK English in most locales, although we use " dollars rather than pounds. This is mostly so I remember things like " excluding or including the ‘u’ in words like 'favourite', depending on the " target audience. I generally use US English for international audiences. " nnoremap u \ :set spelllang=en_us nnoremap z \ :set spelllang=en_nz " The next mapping is also for toggling an option, but it’s more complicated; " it uses a simple plugin of mine called copy_linebreak.vim to manage several " options at once, related to the 'wrap' option that soft-wraps text. " " It’s designed for usage in terminal emulators and multiplexers to " temporarily make the buffer text suitable for copying in such a way that the " wrapping and any associated soft formatting won’t pervert the text, " including 'breakindent', 'linebreak', and 'showbreak' artifacts. " " This is really handy for quick selections of small regions of text. For " larger blocks of text or for manipulating the text as it leaves the buffer, " it makes more sense to use :! commands. " " " "" Leader,b toggles settings friendly to copying and pasting nmap b (CopyLinebreakToggle) " The above mappings show that mappings for toggling boolean options are " simple, but there isn’t a way to toggle single flags within option strings " with just the :set command, so I wrote a plugin called toggle_flags.vim to " provide :ToggleFlag and :ToggleFlagLocal commands. The first argument is " the name of an option, and the second is the flag within it that should be " toggled on or off. "" Leader,a toggles 'formatoptions' ‘a’ auto-flowing flag nnoremap a \ :ToggleFlagLocal formatoptions a "" Leader,L toggles 'colorcolumn' showing the first column beyond 'textwidth' noremap L \ :ToggleFlagLocal colorcolumn +1 ounmap L sunmap L " This mapping uses my paste_insert.vim plugin to queue up automatic commands " for the next insert operation. It’s still pretty new. It replaces my old " paste_open.vim plugin which did this only for opening new lines, and which " kept confusing me. I’m hoping this will be better. "" Leader,p prepares the next insert for paste mode nmap p PasteInsert " These mappings are for managing filetypes. The first one uses the " :ReloadFileType command that was defined much earlier in this file for " application in the vimrc reload command. "" Leader,F reloads filetype settings nnoremap F \ :ReloadFileType "" Leader,t shows current filetype nnoremap t \ :set filetype? "" Leader,T clears filetype nnoremap T \ :set filetype= " These mappings use my put_date.vim plugin for date insertion into the " buffer. "" Leader,d inserts the local date (RFC 2822) nnoremap d \ :PutDate "" Leader,D inserts the UTC date (RFC 2822) nnoremap D \ :PutDate! " This group contains mappings that are to do with file and path management " relative to the current buffer. The Leader,P mapping that creates " directory hierarchies uses the :CreatePath command created earlier. "" Leader,g shows the current file’s fully expanded path nnoremap g \ :echo expand('%:p') "" Leader,G changes directory to the current file’s location nnoremap G \ :cd %:hpwd "" Leader,P creates the path to the current file if it doesn’t exist nnoremap P \ :CreatePath %:h " This group contains mappings that show information about Vim’s internals: " marks, registers, variables, and the like. "" Leader,H shows command history nnoremap H \ :history : "" Leader,k shows my marks nnoremap k \ :marks "" Leader,K shows functions nnoremap K \ :function "" Leader,m shows normal maps nnoremap m \ :nmap "" Leader,M shows buffer-local normal maps nnoremap M \ :nmap "" Leader,S shows loaded scripts nnoremap S \ :scriptnames "" Leader,U shows user commands nnoremap U \ :command "" Leader,v shows all global and internal variables nnoremap v \ :let g: v: "" Leader,V shows all buffer, tab, and window local variables nnoremap V \ :let b: t: w: "" Leader,y shows all registers nnoremap y \ :registers " This group contains mappings concerned with buffer navigation and " management. I use the "jetpack" buffer jumper one a lot. I got it from one " of bairui’s "Vim and Vigor" comics: " " "" Leader,DEL deletes the current buffer nnoremap \ :bdelete "" Leader,INS edits a new buffer nnoremap \ :enew "" Leader,e forces a buffer to be editable, even a :help one nnoremap e \ :set modifiable noreadonly "" Leader,E locks a buffer, reversible with e nnoremap E \ :set nomodifiable readonly "" Leader,j jumps to buffers ("jetpack") nnoremap j \ :buffers:buffer " Leader,o hacks up the list of old files from viminfo just long enough to " ensure that :browse :oldfiles fits in a screen, avoiding an Enter or ‘q’ " keystroke before entering the number. This one is handy followed by " ,\ to jump back to the last remembered position in that file, since " by definition viminfo remembers that mark, too. " nmap o (SelectOldFiles) " This group defines mappings for filtering and batch operations to clean up " buffer text. All of these mappings use commands from my custom plugins: " " :KeepPosition " " :SqueezeRepeatBlanks " " :StripTrailingWhitespace " " "" Leader,x strips trailing whitespace noremap x \ :StripTrailingWhitespace ounmap x sunmap x "" Leader,X squeezes repeated blank lines noremap X \ :SqueezeRepeatBlanks ounmap X sunmap X "" Leader,= runs the whole buffer through =, preserving position nnoremap = \ :KeepPosition execute 'normal! 1G=G' "" Leader,+ runs the whole buffer through gq, preserving position nnoremap + \ :KeepPosition execute 'normal! 1GgqG' " This group defines a few :onoremap commands to make my own text objects. " I should probably make some more of these, as they’ve proven to be " terrifically handy. "" Leader,_ uses last changed or yanked text as an object onoremap _ \ :execute 'normal! `[v`]' "" Leader,% or Leader,5 uses entire buffer as an object onoremap % \ :execute 'normal! 1GVG' omap 5 % " This group defines some useful motions, including navigating by indent " block using a custom plugin: " " " "" Leader,{ and Leader,} move to top and bottom of indent region map { (VerticalRegionUp) sunmap { map } (VerticalRegionDown) sunmap } "" Leader,\ jumps to the last edit position mark: think "Now, where was I?" noremap \ `" sunmap \ " This group does both: useful motions on defined text objects. "" Leader,< and Leader,> adjust indent of last edit; good for pasting nnoremap \ :'[,'] nnoremap > \ :'[,']> " This group is for directory tree or help search convenience mappings. "" Leader,/ types :vimgrep for me ready to enter a search pattern nnoremap / \ :vimgrep /\c/j ** "" Leader,? types :lhelpgrep for me ready to enter a search pattern nnoremap ? \ :lhelpgrep \c " This group contains miscellaneous mappings for which I couldn’t find any " other place. The plugin mappings probably require their own documentation " comment block, but my hands are getting tired from all this typing. " " * " * " * " * " "" Leader,. runs the configured make program into the location list nnoremap . \ :lmake! "" Leader,q formats the current paragraph nnoremap q gqap "" Leader,r acts as a replacement operator map r (ReplaceOperator) ounmap r sunmap r "" Leader,!/1 repeats the last command, adding a bang nnoremap ! \ :! nmap 1 ! "" Leader,#/3 gives me my fortune nmap # (AlternateFileType) nmap 3 # "" Leader,$/4 gives me my fortune nmap $ (Fortune) nmap 4 $ "" Leader,&/7 escapes regex metacharacters map & (RegexEscape) ounmap & sunmap & map 7 & ounmap 7 sunmap 7 "" Leader,*/8 is sticky-star: search, highlight, but don’t move nnoremap * *N nmap 8 * "" Leader,` opens a scratch buffer, horizontally split nnoremap ` \ :ScratchBuffer "" Leader,~ opens a scratch buffer, vertically split nnoremap ~ \ :vertical ScratchBuffer " And last, but definitely not least, I’m required by Vim fanatic law to " include a mapping that reloads my whole configuration. This uses the " command wrapper defined much earlier in the file, so that filetypes also get " reloaded afterwards, meaning I don’t need to follow R with " a F to fix up broken global settings. " nnoremap R \ :ReloadVimrc " I’ll close this file with a few abbreviations. Perhaps of everything in " here, I’m least confident that these should be in here, but they’ve proven " pretty useful. First, some 'deliberate' abbreviations for stuff I type " a lot: " inoreabbrev tr@ tom@sanctum.geek.nz inoreabbrev tr/ " And then, just automatically fix some things I almsot always spell or type " wrnog. " inoreabbrev almsot almost inoreabbrev wrnog wrong inoreabbrev Fielding Feilding inoreabbrev THe The inoreabbrev THere There " Here endeth the literate vimrc. Let us praise God. " " │ Consequently, it is soon recognized that they write for the sake of " │ filling up the paper, and this is the case sometimes with the best " │ authors…as soon as this is perceived the book should be thrown away, " │ for time is precious. " │ " │ —Schopenhauer "