Vim usage notes

Recent Changes

  • Remap <Leader> from “/” to “
  • New wiki commands
  • Vim has been slow returning to normal from insert mode. To fix this I simply changed set timeout timeoutlen=1000 ttimeoutlen=100, which controls how long Vim waits for an additional key to be pressed after matching maps (also explains slowness after “[[”, it’s waiting to match my double bracket map)
  • echom is great for running functions (even your own) and seeing their output in a live Vim session. Useful debugging tool

Multi-line changes

  • Enter visual block mode with ctrl-v
  • Navigate across lines to select locations
  • Enter insert mode with shift-i
  • Type something, then esc to normal mode
  • Typed texted will be repeated across lines

File Hierarchy

  • plugin/: directory for additive function definitions, loaded when Vim is loaded
  • .vimrc: where user-level preferences go, like global options and mappings
  • ftplugin/: filetype plugin related functions

Formatting Lines

Here is a long discussed and particular difficult to resolve controversy: how should lines be formatted? Should they be soft-wrapped by the viewer’s editor? Or should the author hard-wrap them to a fixed length on a new line? How long should the lines be? For the wiki, I’ve long been a proponent of the soft-wrap group; this allowed plugins that operated by line to get the proper context of the whole sentence or paragraph that I wanted. But I’m not sure I need this functionality anymore, and many parsers don’t treat a single new line as a true line break (that is, they still consider next line as immediately following the former). This, along with the benefits of consistent viewing and primarily the additional flexibility in indenting and formatting the hard wrapped text (e.g. with autoindent, some plugins) leads to me to want to try hard wrapping.

Converting between wrap types

Just setting the textwidth or some other formatting options does not mean they will apply and reformat existing text written under different options. Here the gq and a motion should be used to reformat a group of lines.

  • gqip: reformat paragraph, very useful if you don’t want automatic paragraph formatting, but making a change to an already fully formatted paragraph that breaks your line limits.

Format options

  • wrap: when enabled, lines longer the window width will be soft-wrapped to the next line
  • linebreak: when enabled, lines be wrapped so that words aren’t cut off, i.e. it (softly) breaks the newline at the end of the closest word
  • showbreak: string to show at beginning of soft-wrapped lines
  • breakindent: continue soft wrapped line at same indentation level as previous line (requires linebreak to be enabled)
  • textwidth: defines the maximum width of text allowed on one line. Longer lines than the set width will be (hard) broken to the next line
  • columns: sets the number of columns on the screen, changes the size of terminal window (and thus is implicitly set to the windows size at any point in time)
  • autoindent: replicates indent from current line when a new line is created; differs from breakindent as it applies to new (hard) lines instead of soft wrap, and I believe it can be smarter (e.g. properly indent lists)
  • filetype: when enabled, allows Vim to detect the current filetype and load default options (like syntax highlighting)
  • filetype plugin: when enabled, filetype plugins for the currently edited file are loaded
  • filetype indent: when enabled, filetype indent files are loaded for the current file
  • formatoptions: sequence of characters defining how automatic formatting should be performed. Default settings are tcq. See :help fo-table for more.
    • t: autowrap text using textwidth
    • c: autowrap comments using textwidth
    • q: allow gq to reformat comments
    • a: automatically reformat paragraphs when they’re edited
    • n: recognize numbered lists (important for Markdown)
  • comments: Vim’s way of dealing with automatic insertion of comments. These are relevant because they also give us the functionality to define list types (bullets) that behave the same way those comments do. The comments takes a {flags}:{string} structure, where the string is the comment string and the flags define how that command will be allowed to be created and used. fb:- is even a default comment, which allows - (list item) followed by a space to be properly indented. No plugins or any other definitions are even required beyond the default, I just never got to see them because I had so many layers of list modifications on top of it.


Two settings I’ve recently added:

  • highlight clear LineNr
  • highlight clear SignColumn

These make the line number and “sign column” (column for diffs, linting, etc) bars transparent.


Nice source for ^X mode: Vim completion

Faster movement

  • { and } move between blocks of text
  • Ctrl-F and Ctrl-B move screens of text
  • t<char> and T<char> move forward and backward until the next/previous occurrence of <char>
  • y/<search>: yanks forward from current position until the search result
  • d/<search>: deletes forward from current position until the search result
  • * or # searches for the word under the cursor, amazing
  • <Ctrl-R>0 paste last yank (ie basically "0p) in insert mode
  • Consider using c more instead of d when you know you need to insert after; cw for example with delete a word and open insert mode.

My Local Vim Directory

  • .vimrc: holds global settings and mappings to internal/external plugin functions
  • after/plugin/: functions, commands, mappings, etc to be loaded after all other plugins
    • search.vim: search methods and commands for general purpose use; defines DirFzfFiles and DirFzfLines
    • wiki/: folder for wiki related functions and commands
      • search.vim: search commands and functions for the wiki, includes fzf sessions with preview windows for wiki files, lines, backlinks, and unlinks (WikiFzfFiles, WikiFzfLines, WikiFzfBacklinks, and WikiFzfUnlinks, respectively).
      • templates.vim: autocmd template injection for wiki subsystems; for now using Bash scripts, but should be entirely in Vim for convenience
      • links.vim: defines relevant link processing methods and link completion imaps like [[[. I would keep these four mappings in my .vimrc if I could, but there does not seem to be an easy way with the <expr>. Additionally, the fzf#complete method did not respond well to being wrapped by a general function, so I’ve left the four mappings explicit as is.
      • backlinks.vim: defines new backlink buffer scheme for getting file backlinks. This file copies almost all of wikivim’s graph.vim file, but includes my own custom BacklinkBuffer method and command.
      • update_modtime.vim: script to update “modified time” attribute of wiki files. I now use a winview here, which should smooth out jumps on save. Additionally, this method currently uses bash but should be entirely in Vim, like templates.