A very brief introduction to vim’s mapleader

Editor’s note: this is the sixth in a series of posts on vim. If you’re new to vim then this post will make absolutely no sense, so definitely start with the first one which you can find here.

Often touted as one of the strongest cases for vim’s super speedy text editing, is its ability to abbreviate, map or remap keys in order to bend your keyboard to your will. 

abbr
becomes
iabbrev

@@
becomes
[email protected]

Y
becomes
y$

The possibilities are endless.

One problem.

Stock vim has very few unmapped keys by default.

Just about every key on your keyboard does something in vim in normal mode.

w – move to beginning of next word

e – move to the end of the next word

i – enter insert mode

What about uppercase?

Not much better. Almost all the uppercase letters do something too.

It is true that the list of unbound keys in vim is far smaller than the list of bound keys.

Of course you can map certain commands to combinations of keys, there are quite a few more two to three key combinations which are unbound.

But there is a better way… A mapleader.

Your mapleader is both a special, and very ordinary key.

At its simplest, it is really just one good unbound-by-default key that you select as a prefix to a great many mappings that you want to do in vim. When using your mapleader as a prefix, just about every other key on your keyboard is now free to map to your hearts desire.

w jumps to the beginning of the next word in normal mode, but -w doesn’t.

But your mapleader is a little more special than this. It doesn’t just open your whole keyboard as a clean slate for key mappings, it makes the whole process
of mapping keys streamlined and more portable.

First of all,

‘mapleader’ is not just a pet name for your prefix key, it is an actual thing in vim (another variable).

Vim knows that when referring to your <leader> in your vimrc you’re referring to a particular key (whatever you choose it to be), which means whenever you set a key binding in your vimrc you use the phrase <leader>, to signify when you want to use your mapleader and vim knows what you mean.

This has some advantages.

It means you can change your <leader> whenever you like, without having to change every mapping in your vimrc which uses your mapleader (which is damn quick and easy in vim anyway, but whatever). Just change the key which you’ve assigned as your mapleader and <leader> now substitutes that key instead.

It’s portable. Everyone can have a different mapleader.

This will all make much more sense in a minute.

So how do you set your mapleader?

In your vimrc you need to put this somewhere:

let mapleader = "the-key-you-want"

That’s it. Now your mapleader is whatever key you choose to put in quotes.

For example:

let mapleader = "_"

Now, whenever you do a mapping elsewhere in your vimrc (or in any other vimscript) that you want to map your <leader> to, you simply reference it by:

<leader>

For example

nnoremap <leader>v :vsplit $MYVIMRC<cr>

Now vim knows whenever you press _v you want it to … do that other stuff.

Here’s the other stuff (just FYI):

:vsplit – tells vim you want to open up a new buffer and display it next to the current buffer (v stands for ‘vertical’, that is it creates a vertical split between buffers on your screen)

$MYVIMRC – if you remember from my vimrc post is your vimrc environment variable.

<cr> – is the notation for your enter key.

So whenever you press _v vim will split your window vertically into two buffers. One containing your current buffer and one with your vimrc.

The point is, that’s how your mapleader is referenced in Vimscript.

Possible mapleaders

What you set as your mapleader is about as personal as what goes into your vimrc, except that your options are somewhat limited.

So all I’m going to do here is highlight some of the popular options that can be used and explain my honest opinions about them.

Just know that whatever I say is my opinion. The options I outline are all quite popular, and you can make it whatever you want, no judgement.

---

s

Firstly, ‘s’ is my mapleader.

Here’s why.

I’ll start with a caution. ‘s’ already has a function in vim. It is however, totally trivial.

The function of ‘s’ is equivalent to ‘cl’ in normal mode, which is ‘change the character under the cursor’ which means, delete the character under the cursor and enter insert mode.

Here’s why I think this is totally trivial…

‘cl’ is nothing to type out. Nothing at all. More importantly, it is far more intuitive to just use ‘cl’ for ‘changing’ text instead of ‘s’, because you always use it for that anyway. I didn’t know ‘s’ did something until I started learning about mapleaders and which keys were best.

The caveat here, is that ‘x’ is equivalent to ‘dl’. So it seems sensible to have a mapping equivalent to ‘cl’. However, ‘dl’ and ‘x’ leave you in normal mode, and so can be repeated in quick succession, which means ‘xxx’ or ‘5x’ is far easier and faster to do than dldldl. So it makes sense to use ‘x’ for this purpose. It’s also why ‘x’ is such a useful little tool.

‘cl’ by contrast is a one-at-a-time activity. You can only to do it once then you’re in insert mode. It’s two different fingers on two different hands and it’s microseconds of a difference to pressing ‘s’.

I could even argue that ‘cl’ is itself a somewhat redundant action, given that ‘xi’ or ‘dli’ or ‘vc’ will all do the same thing (and ‘xi’ is probably even more intuitive because I use both those keys so often they’re as automatic as breathing).

Finally, I don’t find myself doing that particular action nearly ever anyway. Far more often if I ever change anything, it’s a word, or a whole line.

Here’s why I think it’s the perfect mapleader…

‘s’ is right up in your top ten most accessible and easy to press keys on your keyboard. It’s on your home row after all. Your ring finger literally sits on it when resting.

The majority of your mappings will be followed by some alphanumeric, and it’s so seamless, so intuitive, so natural to follow after ‘s’. ‘s’ is one of the most commonly used non-vowels in the english language, and is very common as the first letter of many words.

It’s just perfect… Too perfect maybe…

I can’t help but wonder if it has some obvious flaw that I’ve missed. Do you know what it is? Tell me!

---

<space>

Using space bar seems to have risen in popularity. Many web pages and vim how-to’s and other stuff from about 2013 onwards can’t stop talking about it.

Your space bar is a perfectly good candidate for a mapleader, but I still prefer ‘s’.

Having said that, your space bar is right up there with your homerow keys in terms of useability. In fact when it comes to writing prose, you probably use your space bar more than any other key on your keyboard. Plus you have two big, fat, strong thumbs to bash away at it with.

So make sure you use your space bar for something really important, something worthy. Something that you will do all the time, something that otherwise takes a long time and a fair amount of effort, or for something very versatile, like your mapleader.

Some possibilities I’ve seen other use it for include:

• mapping it to edit your vimrc (instead of using v as in my above example)
• using it to write the current file (instead of :w) (This is what I use it for)
• using it to write and exit your current file (that seems risky, since you
  might find yourself pressing it a lot accidentally and ZZ is also takes
  no effort)
• Folding (a programmer thing)
• Toggling something important that you use a lot

---

,

The comma is possibly the most common designation for mapleaders. It is a very easy to use key. But I strongly advise against using it.

The problem with using the comma as your mapleader is that it already has a very useful function, which is quite unique.

One more of the many, many navigation tools you have in vim are these:

fX – redraw the cursor at the next instance of X on the current line in the forward direction. Think ‘find’.

FX – redraw the cursor at the next instance of X on the current line in the backward direction.

tX – redraw the cursor immediately before the next instance of X on the current line in the forward direction.

TX – redraw the cursor immediately after the next instance of X on the current line in the backward direction.

; – repeat the most recent action pertaining to f, F, t or T (find the next instance of X)

, – reverse the most recent action pertaining to f, F, t or T (search in the opposite direction)
This will jump your cursor to the next instance of that character. then semi-colon and comma will jump forward and backward to the next instances of that character respectively.

By contrast ‘s’ and space bar both have extremely trivial uses in normal mode and both are benchwarmers.

I understand why the comma could be a popular mapleader, but how it became most popular I’ll never know (probably because it is the example used in the vim documentation). The above commands are indispensible to me I recommend getting into the habit of using them.

If you’re new to vim, do yourself a favour and burn these commands into your muscle memory… and never use ‘,’ as your mapleader!!!!

---

A couple more possibilities which do not seem particularly useful at all are:

_ (underscore)

Why would you set your mapleader to something so far away from your fingers that needs you to <shift> to execute it?

No thanks.

- (dash)

Same thing minus the <shift>

You could use dash, but.. meh.

Finally,

there’s good old backslash

\

Backslash is the default for your mapleader. If you don’t set your mapleader, that’s what vim will use. No doubt there’s plenty of minimalists/purists who are very happy to use this as their mapleader, and why not honestly. It’s certainly better than – or _ if you ask me. If I wasn’t using my MacBook Pro keyboard most of the time, it probably wouldn’t look so small and far away.

Conclusion

So there you have it. My shortest vim post yet.

The humble mapleader is a very powerful key and integral to vim in many ways.

There’s also a ‘localmapleader’ btw. But I’ll leave you to get your head around that one… I can’t make it too easy for you can I?

If you liked this post and want to learn a little bit more about the properly basic basics of vim, then make sure you subscribe/follow my blog.

For more information about me and why I started this blog, make sure you check out my sticky post and my about page.

Happy vimming!