A Vim yellow-belt is bestowed upon a pupil after they use their first g command.

We will begin our foray of g commands with an examination of ga. It is common among the white-belts and black-belts alike to try and remember the g commands with a mnemonic, and given that ga === :ascii perhaps “Get Ascii” can work. It isn’t that bad, but It also isn’t that good… I spent 30 seconds of my life without coming up with something better than that though, so that’s what is getting left there.

Let’s start with an example, foo.json:

{
    "apple": 1,
    "banana": 2,
    "cat": 3
}

When I run :%!jq -r_ within foo.json I get the following error message “jq: parse error: Invalid numeric literal at line 2, column 6”. Well… line 2 column 6 don’t look like no invalid numeric literal to me! Let’s pretend to be Nancy Drew and pull out our investigative toolkit and inspect that character with ga.

Hint: To capture output from a command into a register for reuse at a later point you can utilize the following:

• navigate to line 2 column 6
• :let @a = execute('ascii')
• navigate to line 2 column 5 for comparison
• :let @c = execute('ascii')

Now lets see who’s really hiding under that character!

• Register a) < > 160, Hex 00a0, Oct 240, Digr NS
• Register c) < > 32, Hex 20, Oct 040, Digr SP

It’s Non-Breaking Space! That means our poor developer probably copied something out of a Microsoft Teams message!

“And I would have gotten away with it too if it weren’t for those meddling g commands!”

{
    "apple": 1,
    "banana": 2,
    "cat": 3
}

ga can find use outside of playing detective, it is also a way to see if a digraph is set for a certain non-standard character. A digraph I have setup is 🤮 (yes, you can set emojis up in digraphs how cool is that?!). In order to see what digraph that is set to, I can just navigate my cursor over it and use ga which shows that I have it set to pu:

<🤮> 129326, Hex 0001f92e, Oct 374456, Digr pu

% is a motion that jumps to the respective match of a () [] {}. It was written for working on C originally, so obviously it also works on #if/#else/#endif, and on /* ... */. You can extend it to add in other matching open close tags that suit your fancy like <:>, but if the character is the same such as ":" it won’t work unfortunately.

For my own use in PHP, I wanted to add some support for matching (here|now)docs, and since I needed some regex firepower, I employed the bundled plugin matchit:

packadd! matchit

Now we can start to add in our desired behaviour!

:let b:match_words .= ',<<<["'']\=\(\h\w*\)["'']\=$:^\s*\1\>'

• .= appends to the ftplugin’s existing pairs instead of clobbering them, and the leading , separates our pair from theirs.
• ["'']\= matches 0 or 1 of " or '. '' is how you write a literal ' inside a single-quoted string.
• \h\w* matches an identifier: \h is a letter or underscore, \w is a letter, digit or underscore.
• \(...\) captures the identifier, and \1 reuses it in the end pattern.
• $ and ^\s* anchor the opener to the end of its line and the closer to the start of its line (indent allowed).
• \> is the end of a word, so SQL; matches but SQLX doesn’t.
• the : separates the start pattern from the end pattern.

So now with % we can jump back and forth on the start/end markers for heredocs:

<<<SQL
SELECT * FROM users;
SQL;

or nowdocs:

<<<'HTML'
<div> I <3 blog.nerdware.ca </div>
HTML

Fun fact: I spent an hour of my life troubleshooting the above. I was only able to match on the first < of the <<<. I later found out that matchit uses a greedy matcher and after the first character, it was actually falling back to trying to match the original matchpairs <:> entry… what a wild Friday night. If you got that same issue and want to disable those you can use :setlocal matchpairs-=<:>

If prior to typing % you type a count, it will take you that percentage of the way through the file. I honestly don’t know when this would ever be useful, and I will give it a utility rating on par with g?.

Register

The % register is a special register in Vim that holds the name of your current buffer. I use it to copy the name of the current buffer into my clipboard with :let @+ = @%.

Fun fact: There are a handful of special registers, including + * % # " - : . _ / and =

Command-line Mode

As a range, % means the whole file, (the % in :%s/foo/bar/g).

Elsewhere on the command line, % expands to your buffer name. You can apply all sorts of modifiers to it:

• %:S shell-escapes the output. I wish this were the default setting…
• %:h gives you the directory.
• %:p gives you the full path.
• %:~ slots in ~ for the home directory.
• %:e gives you the extension.

Note: There is some warning somewhere in the Friendly Manual about “%” and %:S working diffently when being passed to an external shell command … I don’t recall the distinction so if you care it can be an excercise to the reader

Here are some examples straight out of the friendly manual (:h filename-modifiers)!

When the file name is “src/version.c”, current dir “/home/mool/vim”:

:p                      /home/mool/vim/src/version.c
:p:.                    src/version.c
:p:~                    ~/vim/src/version.c
:h                      src
:p:h                    /home/mool/vim/src
:p:h:h                  /home/mool/vim
:t                      version.c
:p:t                    version.c
:r                      src/version
:p:r                    /home/mool/vim/src/version
:t:r                    version
:e                      c
:s?version?main?        src/main.c
:s?version?main?:p      /home/mool/vim/src/main.c
:p:gs?/?\\?             \home\mool\vim\src\version.c

Patterns

If you want to group part of a pattern without capturing it, you can use \%\(...\). For example, to make sure a SQL statement is either an update or an insert without caring which: \%(UPDATE\|INSERT\).... It is a niche use, but if you use Vim for scripting because you are like me and hate shell script, you may find the speed advantage helpful, and it doesn’t use up one of your nine \1-\9 backreferences (a benefit I have honestly never needed myself, but a benefit nevertheless).

There is also \%[], which matches as much of a sequence of optional atoms as it can, e.g. fu\%[nction] matches fu, fun, func, up to function.

Error Matching

A topic worth of a dedicated post

A really handy workflow in Vim is using makeprg and errorformat. Together they let you run your build commands, populate the quickfix list with the errors, and allow you to quickly navigate to them. In errorformat, % introduces the format items. Consider the following:

install
└─ install chess_engine
   └─ compile exe chess_engine Debug native 2 errors
src/main.zig:10:36: error: use of undeclared identifier 'argg'
        std.debug.print("{s}\n", .{argg});
                                   ^~~~
src/root.zig:9:18: error: expected ';' after statement
    Engine.move()
                 ^
error: 2 compilation errors
failed command: /usr/bin/zig build-exe -ODebug --dep chess_engine -Mroot=/home/carson/code/zig/chess-engine/src/main.zig -Mchess_engine=/home/carson/code/zig/chess-engine/src/root.zig --cache-dir .zig-cache --global-cache-dir /home/carson/.cache/zig --name chess_engine --zig-lib-dir /usr/lib/zig/ --listen=-

Build Summary: 0/3 steps succeeded (1 failed)
install transitive failure
└─ install chess_engine transitive failure
   └─ compile exe chess_engine Debug native 2 errors

error: the following build command failed with exit code 1:
.zig-cache/o/017f4cbe08099b1eed012c12388c10d5/build /usr/bin/zig /usr/lib/zig /home/carson/code/zig/chess-engine .zig-cache /home/carson/.cache/zig --seed 0x8ff340df -Z9454fa58f76246d2

We could set up our errorformat as follows:

:set makeprg=zig\ build
:set errorformat=%f:%l:%c:\ %t%*[a-z]:\ %m,%-G%.%#
:make

• %f, %l, %c are the file, line and column.
• %t grabs the error type from its first letter (e for error), and %*[a-z] eats the rest of the word.
• %m is the message.
• %-G%.%# ignores every other line (%.%# is errorformat for .*).

And then we get jumped straight to our first error in src/main.zig:10:36 with both that error and the other one populating our quickfix list.

Fluency with the make command in Vim and its various components is a beautiful thing because it means you can spend more time in Vim :)

Fin

So, next time you see a %, take a moment to thank them for all of their hard work.

In Vim, a digraph is taken to be a character outside of our regular keyboard-ascii-reachable range composed of two characters which are in our keyboard-ascii-reachable range. If you are a self loathing patriotism lacking Canadian who uses the EN-US keyboard mapping instead of the EN-CA like myself, it may be helpful to know that with <C-k>e' you can be the pretentious diva you really are and tell people that you didn’t have a coffee, but instead a Caffé Americano.

The digraph in particular that inspired me to write about this is →. I had been looking into a font pack that supported ligeratures in a previous post for converting “->” to “→” when it dawned on me that I had a far simpler solution in my arsenal. I smacked that i for insert mode, I rolled my <C-k> and when my fingers typed ->, I didn’t even need to look at the screen to know it had worked. A stupid smile crept onto my face.

In that moment, I was one with Vim.

Then this morning, I — a carbon based life form — actually needed to employ an em-dash. I closed my eyes and confidently typed <C-k>em. I’m not sure if it was to my dismay or if it was to my chagrin, but when I opened my eyes I was face-to-face with め. I know not from which alphabet nor language that symbol is derived from, but I am quite confident in my assumption that it loosely translates to “Failure”.

I had lost touch with Vim, I had fallen from grace.

There was no time to dwell on this defeat, I still needed an em-dash. I begrudingly opened up :digraphs and began looking for the real McCoy, only to realize that searching for a character that isn’t even on your keyboard is an excerise in futility and a hobby reserved for sadists.

Maybe the kids will judge me for saying so, but I wasted no time and just Googled it, and you better believe I got exactly what I was looking for: <C-k>-M. Now, given that I don’t particularly like that mapping, I decided to exercise my freedoms and ran :digraph em 8212 (The 8212 I got from doing ga in normal mode on the em-dash).

After performing this black magic, I felt like I was becoming one with Vim again. Under a new paradigm, one of understanding that I wasn’t built to become Vim, but that Vim was built to become me, and that I am <C-k>em = —, and now Vim is too.

1. Remap your capslock key. Now now, don’t go telling me “Carson, I already did that, Capslock → ^[ did not get me any girlies” because I wasn’t going to tell you to remap it to escape! Remap that sucka to Left Ctrl. Why would you want this? E-R-G-O-N-O-M-I-C-S. When you make your sensai proud and finally get past that Vim white-belt, you will begin to realize that sliding your pinky down to do all of these necessary actions like <C-x>, <C-o>, or <C-k> when you are in insert mode is wasting time and muscular stamina for your that little itty bitty finger.
2. So, what about escape then? You still use an escape key? No wonder you haven’t been noticed by the hunnies yet. How about you grow up and start using <C-[> like a real man. Pair this with tip #1 for spectacular results.
3. Set your Man pager to Vim with export MANPAGER="nvim +Man!". No, like seriously, do that now. No more sobbing because you can never figured out what the heck to do with curl(4), just <Shift-k> yourself around town like the baller you are.
4. Use these keyboard shortcuts for adding clipboard support because they are scientifically proven to be superior:

   " Neovim
   vim.keymap.set("x", "<leader>y", '"+y', { desc = "Yank selection to system clipboard" })
   vim.keymap.set("x", "<leader>Y", '"+d', { desc = "Cut selection to system clipboard" })
   vim.keymap.set({ "n", "x" }, "<leader>p", '"+p', { desc = "Paste from system clipboard" })
   

   Note: Some people have issues getting clipboard working. But as the kids say on Stack Overflow, Read the Friendly Manual :h provider-clipboard.

5. Whatever you do, stay away from Neovim starter packs. These reek of someone who is trying to be cool. The first rule of being cool is to not look like you’re trying to be cool. When I first made the switch away from JetBrains, I started with Lazyvim, and still to this day, if you get too close to me you will get a whiff of that rancid poser stench.
6. Rely on LLM’s for every detail of your life and can’t determine how many r’s to put in strawberry? Just hit a word with <C-x> <C-s> in insert mode (after having run :set spell), or z= in normal mode to use the built-in spell-checker.
7. Forgot to capitalize your name? Are you still navigating back to the first letter of the word with b and then using r to replace with the upper case character? Why not use ~ instead! Feel like capitalizing the whole word? Then guiw is your friend!
8. Okay so you finished vim-tutor and know about w to go to the next word, but how about W to use the next whitespace as your word boundary!? You can pair that with other commands like diW to make entries from lists go POOF! And just because I am feeling generous, I will let you know it works with b and B as well. Not even charging you an extra tip for that.
9. Read crontabs? Then hold onto your hat because this two-fer tip will rock your sox. vim -M /etc/crontab opens up your buffer in unmodifiable mode, which means you will have to try really hard to screw things up this time. Once you are in crontab, want to know the contents of /etc/cron.hourly? Navigate to it in normal mode and use gf to go to the file

   Note: gf command does not give you a gf.

10. And, for big tip number ten, touch grass.

Note: I use Neovim as my daily driver. I don’t use native Vim that often, but I hear LSP support is better in Neovim than Vim.

As of the time of writing, I have had a 0% success rate in making any converts to the church of Vim. The heretics are usually split between “I already know this IDE” and “Vim doesn’t have the functionality of my IDE”. To the former, we call that Stockholm Syndrome. To the latter, we call that ignorance.

Today we will discuss why Vim can do most of what your fancy-dancy editor does, and more. I will cover the most common objections, namely: Database integration, Version control integration, Language Server Protocol support (not that most people actually know to call it that), a plugin ecosystem, and remote development support. What you will find, is that all of these are from plugins, but that is sorta the point. Get what you want, nothing more, nothing less.

Databases

Tim Pope has an incredible plugin called vim-dadbod. This plugin gives you access to databases with customizable configurations for all of the big names. Once you have this up and running you can execute sql chunks from files, entire files, or adhoc queries and get autocomplete results as you write.

Version control integration (git, of course)

Well, tpope saves the day again with vim-fugitive. You can simply issue your cli git commands in Command-line mode, have an intuitive UI, and customize it to your liking. When combined (optionally) with diffview for reviewing diffs of a specific file or commit, and gitsigns for gutter markup and jumping to hunks, you really get all of the gitting you could possibly need.

Language Server Protocol

Some people have a tough time getting started with LSP’s, but that’s only because of a skill issue. It’s really simple, and there are a thousand videos on the topic if you prefer that to just reading the docs :h lsp. Below is an example of all that can be needed sometimes for a configuration (Which is almost 100% copy paste from the README):

local vim = vim

-- Install `ziglang/zig.vim` using the built-in plugin manager (Neovim 0.12.0+)
-- A tool like `vim-plug` or `lazy.nvim` can also be used instead.
vim.pack.add({
  'https://codeberg.org/ziglang/zig.vim',
})

-- don't show parse errors in a separate window
vim.g.zig_fmt_parse_errors = 0
-- disable format-on-save from `ziglang/zig.vim`
vim.g.zig_fmt_autosave = 0
-- enable  format-on-save from vim.lsp + ZLS
--
-- Formatting with ZLS matches `zig fmt`.
vim.api.nvim_create_autocmd('BufWritePre', {
  pattern = { "*.zig", "*.zon" },
  callback = function(ev)
    vim.lsp.buf.format()
  end
})

vim.lsp.config['zls'] = {
  -- Set to 'zls' if `zls` is in your PATH
  cmd = { '/home/carson/.config/nvim/lua/lang/zls/zig-out/bin/zls' },
  filetypes = { 'zig' },
  root_markers = { 'build.zig' },
  -- There are two ways to set config options:
  --   - edit your `zls.json` that applies to any editor that uses ZLS
  --   - set in-editor config options with the `settings` field below.
  --
  -- Further information on how to configure ZLS:
  -- https://zigtools.org/zls/configure/
  settings = {
    zls = {
      -- Whether to enable build-on-save diagnostics
      --
      -- Further information about build-on save:
      -- https://zigtools.org/zls/guides/build-on-save/
      -- enable_build_on_save = true,

      -- omit the following line if `zig` is in your PATH
      zig_exe_path = '/usr/bin/zig'
    }
  },
}
vim.lsp.enable('zls')

With those lines I get first class editor support when working with Vim.

Plugin ecosystem

As you might have picked up on from reading the above sections, there is infact a plugin ecosystem for Vim. There are a ton of different plugins, plugin managers, and ways to integrate them all. I personally use vim.pack which is native, but I believe most people use Mason. Part of Bram’s vision with Vim was a tight consistent core that could be extended by individuals as they saw fit. I find this part alone to be such a compelling argument for using Vim. It is the idea that Vim is a Personalized Development Environment (I know the phrase is attributed to tj_devries but I coulda sworn I heard it in someone’s conference talk before that… anywho…). I can keep my editor lightweight, and bring in things as I want or need them, for instance I absolutely love the nvim-surround plugin so I can do things like changing a surrounding parenthesis to a bracket or changing a surrounding function. But if you didn’t like having that kind of power at your fingertips (coward!), you are not forced to include it in your editor.

Remote development

This is a bit embarassing, but I actually did not have this set up until quite recently. I work on a few codebases that have remote development dev environments, and I had been leaving my JetBrains IDE in a hidden tab in order to keep my remote development code flow working. Eventually, I admitted the error of my ways, and just added in two simple additions to my .nvim.lua file (namely a PostBufWrite rsync, and a function RsyncProj that I can use to sync over all of the files after something like a git branch switch). It took a little bit of trial and error to get my excludes working as intended, but I think I had it all working in only a few hours.

Some bonuses you don’t get from other editors

• Macros
• Registers
• Vim-motions
• Modes
• Developing an unhealthy superiority complex
• Quickfix List
• Can work on any remote server with your same daily setup (either running Vim on the server or via netrw-transparent)

:w
E212: Can't open file for writing: no such file or directory

Maybe you try one of these three options:

1. :qa! and call it quits for the day.
2. <C-z> → mkdir -p foo/bar/ → fg → :w
3. :!mkdir -p %:h → :w

Each of those may solve the problem, but there is a better way: Neovim comes with a flag to save you from any nastiness, :w ++p. It creates the missing parent directories for you before writing.

Note: On option 3: %:h is not shell-escaped. That can lead to some not so fun unintended consequences, specifically when doing something like :!rm %. Add the :S modifier to escape it safely: :!mkdir -p %:h:S.

It actually became evident to me while writing the Note above that many people probably don’t know the magic of the % shortcut. On the command line, % expands to the current file name, and it allows for modifiers to do things like:

• %:h the directory part (drops the file name)
• %:~ the path relative to your home directory (~/...)
• %:e the extension of the file name
• %:S the file name escaped for use in a shell command

I’ll probably write a dedicated post on this at some point, because it is a great utility to have under your belt.

Okay, but Carson, the real headache for me is when I try to edit a file that I actually don’t have permission for!

Ah, yes, the ol’ E45, then E212.

In Vim you can do the following:

" Vim
:w !sudo tee %:S >/dev/null

And remember kids, :w !sudo ≠ :w! sudo

Whereas Neovim’s :! runs in a noninteractive shell connected over a pipe into a terminal, so sudo has nowhere to ask for your password. Instead, write to a temporary file and copy it back from a terminal buffer instead:

" Neovim
:w /tmp/foobar
:terminal sudo cp /tmp/foobar %:S

Also, if you have passwordless sudo on, I think you could maybe just do a sudo write without anything special. I am too lazy to verify that myself though, call it an exercise for the reader.

3. Tax Filings Q10
4. Legal Documents Q4
12. Payroll Information Q1
1. Some Important File Q2

Hint: if you are following along, you may want to copy that block and put it into a named register for reuse. Since this is the first vim-tip I’ll just add that you can navigate to the 3. Tax Filings Q10 line, hit Shift+V to enter Visual Line Mode, 3j to select the other lines, then "dy where d is just a named register that I am using so I can remember it with the mnemonic demo. To reuse it, you can put it with "dp.

How might you go about sorting this? Perhaps you think you are pretty clever with the :move command and use it on each line with :m .(+|-)n until it is sorted. Or maybe you’re a prompt engineer and get Claude to do it by highlighting the range and invoking :'<,'>!claude -p "Sort this list -- make no mistakes!". Maybe. But, what if you could instead be a Vim power user and invoke the :sort command on this list?

By default, :sort on that list will only do lexicographic sorting:

:sort
1. Some Important File Q2
12. Payroll Information Q1
3. Tax Filings Q10
4. Legal Documents Q4

Which gets us part way there, but has the unfortunate side effct of giving us PTSD of using Excel and trying to sort a column only to realize that it’s formatted as Text. Thankfully, Vim provides us with an optional n flag to the sort command that sorts by the first numeric value it comes across in each line:

:sort n
1. Some Important File Q2
3. Tax Filings Q10
4. Legal Documents Q4
12. Payroll Information Q1

Hooray! We can go to our boss and let him know that this business-critical task has been taken care of. But, oh no, what’s this? He actually wanted it sorted by the Business Quarter first?! This is where individuals using JetBrains IDEs would throw in the towel and start looking for a new job, not us though, we’re special because we use Vim.

:sort has a pattern argument that skips part of each line when sorting. For us, we can exclude everything up to and including the Q:

:sort n /.*Q/
12. Payroll Information Q1
1. Some Important File Q2
4. Legal Documents Q4
3. Tax Filings Q10

I would be remiss to not take an opportunity to point out that you can also shell out to a native sort utility (gnu sort for me):

:'<,'>!sort -n
1. Some Important File Q2
3. Tax Filings Q10
4. Legal Documents Q4
12. Payroll Information Q1

:'<,'>!sort -n -tQ -k2
12. Payroll Information Q1
1. Some Important File Q2
4. Legal Documents Q4
3. Tax Filings Q10