Scripting

At some point, mappings and settings aren't enough. You want Vim to do something truly custom — create a backup with a timestamp, open all git-modified files, or build a mini-plugin for your team. That's when you reach for scripting.

Vim has its own scripting language, Vimscript, which has been around since the early days. It's quirky but powerful, and a lot of existing plugins and configurations use it. Neovim adds first-class support for Lua — a fast, clean language that makes writing plugins and complex configurations genuinely enjoyable.

This chapter teaches both. We start with Vimscript fundamentals and useful patterns, then transition to Lua scripting with Neovim's rich API. By the end, you'll be able to write your own functions, commands, and even simple plugins.

What you'll learn in this chapter:

• Write Vimscript functions using variables, conditionals, loops, and the Preserve pattern

• Create custom commands with arguments and range support

• Use Lua to script Neovim with its buffer, window, and autocommand APIs

• Build a simple Neovim plugin from scratch using the Lua module pattern

• Leverage floating windows, user commands, and notifications in Neovim's API

Vimscript Basics

Variables

let g:my_var = 'global variable'     " Global
let b:my_var = 'buffer-local'        " Buffer-local
let w:my_var = 'window-local'        " Window-local
let s:my_var = 'script-local'        " Script-local
let l:my_var = 'function-local'      " Function-local
let &option = 'value'                " Set an option
let @a = 'register content'          " Set a register

Functions

function! MyFunction(arg1, arg2)
    echo 'Arguments: ' . a:arg1 . ' ' . a:arg2
    return a:arg1 + a:arg2
endfunction

" Call it
:call MyFunction(1, 2)
:echo MyFunction(1, 2)

Conditionals

if condition
    " ...
elseif other_condition
    " ...
else
    " ...
endif

Loops

" For loop
for item in ['one', 'two', 'three']
    echo item
endfor

" While loop
let i = 0
while i < 10
    let i += 1
endwhile

The Preserve Pattern

A common pattern for functions that should not disturb the user's context:

if !exists('*Preserve')
    function! Preserve(command)
        try
            let l:win_view = winsaveview()
            silent! execute 'keepp keepj ' . a:command
        finally
            call winrestview(l:win_view)
        endtry
    endfunction
endif

" Usage: preserve cursor position while running a command
:call Preserve(':%s/\s\+$//e')
nnoremap <leader>= :call Preserve('normal! gg=G')<CR>

Tip: The Preserve pattern is especially useful in autocommands and mappings (see Mappings) where you want to run a command without disrupting the user's cursor position or search history.

Guards

Prevent functions from being defined multiple times:

if !exists('*MyFunction')
    function! MyFunction()
        " ...
    endfunction
endif

Useful Function: WriteBackup

Create a timestamped backup of the current file without changing the modified state:

fun! WriteBackup()
    let _modified = &modified
    let fname = expand("%:p:r") . "." . strftime("%Y%m%d-%H%M") . "." . expand("%:e")
    silent exe ":w " . fnameescape(fname)
    let &modified = _modified
    echo "Wrote " . fname
endfun
nnoremap <Leader>ba :call WriteBackup()<CR>

This saves a copy like myfile.20260228-1430.py while keeping the original file's modified state unchanged.

Useful Function: StripTrailingWhitespace

Remove trailing whitespace without moving the cursor (using the Preserve pattern):

fun! StripTrailingWhitespace()
    call Preserve(':%s/\s\+$//e')
endfun
command! Strip :call StripTrailingWhitespace()

" Auto-strip on save for specific filetypes
augroup strip_whitespace
    autocmd!
    autocmd BufWritePre *.py,*.lua,*.vim call StripTrailingWhitespace()
augroup END

Useful Function: OpenChangedFiles

Open all files that have been modified in git (useful after git stash pop or merges). This pairs well with the multi-file workflows in (see Advanced Patterns & Workflows):

function! OpenChangedFiles()
    only
    let status = system('git status -s | grep "^\s*[MA]" | cut -c4-')
    for file in split(status, "\n")
        exec "edit " . fnameescape(file)
    endfor
endfunction
command! OpenChanged :call OpenChangedFiles()

Useful Pattern: Custom Commands with Arguments

" Create a command that accepts arguments
command! -nargs=1 Google silent! execute '!xdg-open "https://google.com/search?q=' . <q-args> . '"'
" Usage: :Google vim text objects

" Create a command that works on a range
command! -range Reverse <line1>,<line2>g/^/m<line1>-1
" Usage: select lines, then :Reverse

Lua Scripting for Neovim

For an introduction to Lua in the context of Neovim configuration, see (see Neovim and Lua). This section goes deeper into the language itself.

Variables and Types

local str = 'hello'         -- string
local num = 42               -- number
local float = 3.14           -- float
local bool = true            -- boolean
local tbl = { 1, 2, 3 }     -- table (list)
local dict = { key = 'val' } -- table (dictionary)
local fn = function() end    -- function

Functions

-- Named function
local function greet(name)
    return 'Hello, ' .. name .. '!'
end

-- Anonymous function
local greet = function(name)
    return 'Hello, ' .. name .. '!'
end

-- Multiple return values
local function min_max(tbl)
    return math.min(unpack(tbl)), math.max(unpack(tbl))
end

Tables

Tables are Lua's only data structure — they serve as arrays, dictionaries, objects, and more:

-- Array-like table (1-indexed!)
local fruits = { 'apple', 'banana', 'cherry' }
print(fruits[1])  -- 'apple'
print(#fruits)    -- 3 (length)

-- Dictionary-like table
local config = {
    theme = 'dark',
    font_size = 14,
}
print(config.theme)       -- 'dark'
print(config['font_size']) -- 14

-- Iterate
for i, fruit in ipairs(fruits) do
    print(i, fruit)
end

for key, value in pairs(config) do
    print(key, value)
end

String Operations

-- Concatenation
local full = 'hello' .. ' ' .. 'world'

-- String formatting
local msg = string.format('Hello, %s! You are %d years old.', 'John', 30)

-- Pattern matching (Lua patterns, not regex)
local year = string.match('2026-02-28', '(%d+)%-')

Writing a Simple Neovim Plugin

Plugin Structure

A Lua plugin for Neovim follows this structure:

~/.config/nvim/lua/myplugin/
├── init.lua        -- Main module
└── utils.lua       -- Helper functions

Example: Word Counter Plugin

-- ~/.config/nvim/lua/wordcount/init.lua
local M = {}

function M.count_words()
    local lines = vim.api.nvim_buf_get_lines(0, 0, -1, false)
    local count = 0
    for _, line in ipairs(lines) do
        for _ in line:gmatch('%S+') do
            count = count + 1
        end
    end
    vim.notify(string.format('Word count: %d', count), vim.log.levels.INFO)
    return count
end

function M.setup(opts)
    opts = opts or {}
    vim.api.nvim_create_user_command('WordCount', function()
        M.count_words()
    end, { desc = 'Count words in buffer' })

    if opts.keymap then
        vim.keymap.set('n', opts.keymap, M.count_words, { desc = 'Count words' })
    end
end

return M

Use it in your config:

require('wordcount').setup({ keymap = '<leader>wc' })

Neovim API Highlights

Buffer Operations

-- Get all lines
local lines = vim.api.nvim_buf_get_lines(0, 0, -1, false)

-- Set lines
vim.api.nvim_buf_set_lines(0, 0, 0, false, { 'First line' })

-- Get/set buffer options
local ft = vim.bo.filetype           -- short form
local ft = vim.api.nvim_get_option_value('filetype', { buf = 0 })  -- full form

-- Buffer info
local name = vim.api.nvim_buf_get_name(0)
local modified = vim.bo.modified
local line_count = vim.api.nvim_buf_line_count(0)

Window Operations

-- Get cursor position {row, col} (1-indexed row, 0-indexed col)
local pos = vim.api.nvim_win_get_cursor(0)

-- Set cursor
vim.api.nvim_win_set_cursor(0, { 10, 0 })  -- Go to line 10, col 0

-- Window dimensions
local width = vim.api.nvim_win_get_width(0)
local height = vim.api.nvim_win_get_height(0)

Floating Windows

-- Create a floating window
local buf = vim.api.nvim_create_buf(false, true)
vim.api.nvim_buf_set_lines(buf, 0, -1, false, { 'Hello from floating window!' })

local win = vim.api.nvim_open_win(buf, true, {
    relative = 'editor',
    width = 40,
    height = 3,
    col = (vim.o.columns - 40) / 2,
    row = (vim.o.lines - 3) / 2,
    style = 'minimal',
    border = 'rounded',
})

Autocommands

-- Create an autocommand group (prevents duplicates on re-source)
local augroup = vim.api.nvim_create_augroup('MyGroup', { clear = true })

-- Highlight on yank
vim.api.nvim_create_autocmd('TextYankPost', {
    group = augroup,
    callback = function()
        vim.highlight.on_yank({ timeout = 200 })
    end,
})

-- Set options for specific filetypes
vim.api.nvim_create_autocmd('FileType', {
    group = augroup,
    pattern = { 'python', 'lua' },
    callback = function()
        vim.opt_local.shiftwidth = 4
        vim.opt_local.tabstop = 4
    end,
})

-- Return to last edit position when opening files
vim.api.nvim_create_autocmd('BufReadPost', {
    group = augroup,
    callback = function()
        local mark = vim.api.nvim_buf_get_mark(0, '"')
        local line_count = vim.api.nvim_buf_line_count(0)
        if mark[1] > 0 and mark[1] <= line_count then
            pcall(vim.api.nvim_win_set_cursor, 0, mark)
        end
    end,
})

User Commands

-- Simple command
vim.api.nvim_create_user_command('Hello', function()
    vim.notify('Hello from Neovim!')
end, { desc = 'Say hello' })

-- Command with arguments
vim.api.nvim_create_user_command('Grep', function(opts)
    vim.cmd('silent grep! ' .. opts.args)
    vim.cmd('copen')
end, { nargs = '+', desc = 'Grep and open quickfix' })

-- Command with range
vim.api.nvim_create_user_command('Reverse', function(opts)
    local lines = vim.api.nvim_buf_get_lines(0, opts.line1 - 1, opts.line2, false)
    local reversed = {}
    for i = #lines, 1, -1 do
        table.insert(reversed, lines[i])
    end
    vim.api.nvim_buf_set_lines(0, opts.line1 - 1, opts.line2, false, reversed)
end, { range = true, desc = 'Reverse selected lines' })

Notifications

vim.notify('Info message', vim.log.levels.INFO)
vim.notify('Warning!', vim.log.levels.WARN)
vim.notify('Error!', vim.log.levels.ERROR)

Tip: Install nvim-notify for beautiful notification popups.

Summary

Vimscript and Lua are complementary tools for extending your editor beyond what mappings and settings alone can achieve. Vimscript remains essential for understanding existing plugins and writing portable configurations, while Lua unlocks Neovim's full potential with a cleaner syntax, better performance, and access to the rich vim.api surface. Whether you write a one-off function or a full plugin, scripting is what turns Vim from a text editor into your personal development environment.

Key takeaways:

• Vimscript variables use scope prefixes (g:, b:, s:, l:) that make their visibility explicit and prevent naming collisions.

• The Preserve pattern and guard checks are essential idioms for writing robust Vimscript functions that behave well in any context.

• Lua tables serve as arrays, dictionaries, and objects, making them the single data structure you need to master for Neovim scripting.

• Neovim's vim.api provides programmatic access to buffers, windows, autocommands, and user commands -- everything you need to build plugins.

Exercises

1. Write a Vimscript function — Create a function called InsertDate() that inserts the current date at the cursor position. Map it to <leader>id (see Mappings).

2. Create a custom command with arguments — Write a Vimscript command :Wrap that wraps the current visual selection with a given HTML tag. For example, :Wrap div should wrap the selection with <div> and </div>.

3. Lua: Create a floating window — Write a Lua function that opens a centered floating window displaying the contents of the current buffer's filename and line count.

4. Lua: Write a word counter plugin — Extend the word counter example from this chapter to also count characters and display both counts in a notification. Add a setup function that creates a :Stats command.

5. Autocommand in Lua — Write a Lua autocommand that automatically strips trailing whitespace from .py and .lua files on save, without moving the cursor. Use the Preserve pattern concept.