Vim Script

Google Vim Script Style Guide

Official Google Vim script coding standards for consistent plugin development.

Golden Rules

1. Use `scriptencoding utf-8` — declare encoding at top of every file 2. Prefix plugin functions — avoid namespace collisions with other plugins 3. Use `abort` on functions — fail fast on errors instead of silently continuing 4. Check feature availability — use has('feature') before using features 5. Avoid global variables — use script-local s: instead of g: internally 6. Document all commands — help users understand usage 7. Test on multiple Vim versions — ensure broad compatibility

Quick Reference

Naming Conventions

File Structure

" ✓ CORRECT - file header and guard
" Plugin: MyPlugin
" Description: Does something useful
" Maintainer: Your Name <email@example.com>
" License: Apache 2.0

if exists('g:loaded_myplugin')
  finish
endif
let g:loaded_myplugin = 1

scriptencoding utf-8

" Plugin code here

Functions

" ✓ CORRECT - autoloaded function with abort
function! myplugin#ProcessBuffer() abort
  let l:lines = getline(1, '$')
  for l:line in l:lines
    call s:ProcessLine(l:line)
  endfor
endfunction

" ✓ CORRECT - script-local helper function
function! s:ProcessLine(line) abort
  if empty(a:line)
    return
  endif
  echo a:line
endfunction

" ✓ CORRECT - function with optional arguments
function! myplugin#Greet(...) abort
  let l:name = a:0 >= 1 ? a:1 : 'World'
  echo 'Hello, ' . l:name . '!'
endfunction

Variables and Scoping

" ✓ CORRECT - explicit scoping
function! myplugin#Example() abort
  let l:local_var = 'local'
  let s:script_var = 'script'

  " Check before using global config
  if exists('g:myplugin_config')
    let l:config = g:myplugin_config
  else
    let l:config = {}
  endif

  echo l:local_var
endfunction

Commands

" ✓ CORRECT - custom commands
command! -nargs=0 MyPluginRun call myplugin#Run()
command! -nargs=1 MyPluginGreet call myplugin#Greet(<f-args>)
command! -range MyPluginProcess <line1>,<line2>call myplugin#ProcessRange()
command! -nargs=1 -complete=file MyPluginOpen call myplugin#Open(<f-args>)

Mappings

" ✓ CORRECT - non-recursive mappings with <silent>
nnoremap <silent> <Leader>mp :call myplugin#Process()<CR>
vnoremap <silent> <Leader>ms :call myplugin#ProcessSelection()<CR>
inoremap <silent> <C-Space> <C-R>=myplugin#Complete()<CR>

" ✓ CORRECT - buffer-local mapping
nnoremap <buffer> <silent> <Leader>mp :call myplugin#ProcessBuffer()<CR>

Autocommands

" ✓ CORRECT - always use augroup to avoid duplicate autocommands
augroup MyPlugin
  autocmd!
  autocmd BufRead,BufNewFile *.txt call myplugin#SetupTextFile()
  autocmd FileType python call myplugin#SetupPython()
  autocmd VimLeave * call myplugin#Cleanup()
augroup END

Error Handling

" ✓ CORRECT - try-catch for risky operations
function! myplugin#SafeOperation() abort
  try
    call myplugin#RiskyFunction()
  catch /^Vim\%((\\a\+)\)\=:E/
    echoerr 'Operation failed: ' . v:exception
  finally
    call myplugin#Cleanup()
  endtry
endfunction

" ✓ CORRECT - checking for required executables
if !executable('git')
  echoerr 'myplugin: git not found in PATH'
  finish
endif

Feature Detection

" ✓ CORRECT - check features before using them
if has('python3')
  python3 import myplugin
elseif has('python')
  python import myplugin
else
  echoerr 'myplugin requires Python support'
  finish
endif

" ✓ CORRECT - check Vim version
if v:version < 800
  echoerr 'myplugin requires Vim 8.0+'
  finish
endif

String Operations

" ✓ CORRECT - case-sensitive comparison
if l:str ==# 'exact'
  echo 'Case-sensitive match'
endif

" ✓ CORRECT - case-insensitive comparison
if l:str ==? 'case'
  echo 'Case-insensitive match'
endif

" ✓ CORRECT - string concatenation
let l:message = 'Hello, ' . l:name . '!'

Common Mistakes

When to Use This Guide

• Writing Vim plugins
• Maintaining Vim configuration files
• Code reviews for Vimscript
• Onboarding new contributors to Vim plugin projects

Install

npx skills add testdino-hq/google-styleguides-skills/vim-script

Full Guide

See vim-script.md for complete details, examples, and edge cases.

Google Vim Script Style Guide

Source: https://google.github.io/styleguide/vimscriptguide.xml

Golden Rules

1. Use 2-space indentation — for readability 2. Prefix plugin functions — with plugin name 3. Use `abort` on functions — for error handling 4. Prefer `scriptencoding utf-8` — at top of file 5. Use `l:` for local variables — explicit scoping 6. Document all functions — with comments

---

1. File Structure

" CORRECT - file header
" Plugin: MyPlugin
" Description: Does something useful
" Maintainer: Your Name <email@example.com>
" License: Apache 2.0

if exists('g:loaded_myplugin')
  finish
endif
let g:loaded_myplugin = 1

scriptencoding utf-8

" Plugin code here

---

2. Naming

" CORRECT - function naming
function! myplugin#ProcessBuffer() abort
  let l:lines = getline(1, '$')
  " Process lines
endfunction

" CORRECT - variable scoping
let g:myplugin_enabled = 1
let s:internal_counter = 0

---

3. Functions

" CORRECT - function with abort
function! myplugin#CalculateTotal(numbers) abort
  " Calculate sum of numbers
  let l:total = 0
  for l:num in a:numbers
    let l:total += l:num
  endfor
  return l:total
endfunction

" CORRECT - function with range
function! myplugin#ProcessRange() range abort
  for l:line_num in range(a:firstline, a:lastline)
    let l:line = getline(l:line_num)
    " Process line
  endfor
endfunction

" CORRECT - function with optional arguments
function! myplugin#Greet(...) abort
  let l:name = a:0 >= 1 ? a:1 : 'World'
  echo 'Hello, ' . l:name . '!'
endfunction

---

4. Variables

" CORRECT - explicit scoping
function! myplugin#Example() abort
  let l:local_var = 'local'
  let s:script_var = 'script'
  let g:global_var = 'global'
  
  " Use variables
  echo l:local_var
endfunction

" CORRECT - checking if variable exists
if exists('g:myplugin_config')
  let l:config = g:myplugin_config
else
  let l:config = {}
endif

---

5. Conditionals

" CORRECT - if statement
if condition
  " Do something
elseif other_condition
  " Do something else
else
  " Default action
endif

" CORRECT - checking for features
if has('python3')
  " Use Python 3
elseif has('python')
  " Use Python 2
else
  echoerr 'Python not available'
endif

---

6. Loops

" CORRECT - for loop
for l:item in l:items
  echo l:item
endfor

" CORRECT - while loop
let l:i = 0
while l:i < 10
  echo l:i
  let l:i += 1
endwhile

" CORRECT - iterating over range
for l:i in range(1, 10)
  echo l:i
endfor

---

7. Commands

" CORRECT - define custom command
command! -nargs=1 MyPluginGreet call myplugin#Greet(<f-args>)

" CORRECT - command with range
command! -range MyPluginProcess <line1>,<line2>call myplugin#ProcessRange()

" CORRECT - command with completion
command! -nargs=1 -complete=file MyPluginOpen call myplugin#Open(<f-args>)

---

8. Mappings

" CORRECT - normal mode mapping
nnoremap <silent> <Leader>mp :call myplugin#Process()<CR>

" CORRECT - visual mode mapping
vnoremap <silent> <Leader>mp :call myplugin#ProcessSelection()<CR>

" CORRECT - insert mode mapping
inoremap <silent> <C-Space> <C-R>=myplugin#Complete()<CR>

" CORRECT - buffer-local mapping
nnoremap <buffer> <silent> <Leader>mp :call myplugin#ProcessBuffer()<CR>

---

9. Autocommands

" CORRECT - autocommand group
augroup MyPlugin
  autocmd!
  autocmd BufRead,BufNewFile *.txt call myplugin#SetupTextFile()
  autocmd FileType python call myplugin#SetupPython()
augroup END

---

10. Error Handling

" CORRECT - try-catch
function! myplugin#SafeOperation() abort
  try
    " Risky operation
    call myplugin#RiskyFunction()
  catch /^Vim\%((\a\+)\)\=:E/
    echoerr 'Operation failed: ' . v:exception
  finally
    " Cleanup
    call myplugin#Cleanup()
  endtry
endfunction

" CORRECT - checking for errors
if !executable('git')
  echoerr 'Git not found'
  finish
endif

---

11. String Operations

" CORRECT - string concatenation
let l:message = 'Hello, ' . l:name . '!'

" CORRECT - string comparison
if l:str ==# 'exact'  " Case-sensitive
  echo 'Match'
endif

if l:str ==? 'case'  " Case-insensitive
  echo 'Match'
endif

" CORRECT - string functions
let l:upper = toupper(l:str)
let l:lower = tolower(l:str)
let l:trimmed = trim(l:str)

---

12. Lists and Dictionaries

" CORRECT - lists
let l:items = ['apple', 'banana', 'cherry']
let l:first = l:items[0]
call add(l:items, 'date')

" CORRECT - dictionaries
let l:config = {
      \ 'host': 'localhost',
      \ 'port': 8080,
      \ 'enabled': 1
      \ }
let l:host = l:config['host']
let l:port = get(l:config, 'port', 80)

---

Common Mistakes