SnipMate

SnipMate aims to provide support for textual snippets, similar to TextMate or other Vim plugins like UltiSnips. For example, in C, typing for<tab> could be expanded to

for (i = 0; i < count; i++) {
    /* code */
}

with successive presses of tab jumping around the snippet.

Originally authored by Michael Sanders, SnipMate was forked in 2011 after a stagnation in development. This fork is currently maintained by Rok Garbas, Marc Weber, and Adnan Zafar.

Installing SnipMate

SnipMate can be installed using a package manager or using Vim's built-in package handling. It does depend on vim-addon-mw-utils and optionally tlib. For example, to use Vim's built-in support,

% mkdir -p ~/.vim/pack/SnipMate/start
% cd ~/.vim/pack/SnipMate/start
% git clone https://github.com/garbas/vim-snipmate.git
% git clone https://github.com/MarcWeber/vim-addon-mw-utils.git

# Optional:
% git clone https://github.com/tomtom/tlib_vim.git
% git clone https://github.com/honza/vim-snippets.git

NOTE: SnipMate does not ship with any snippets out of the box. We suggest looking at the vim-snippets repository.

If tlib is enabled, it is used for multisnip (:h SnipMate-multisnip). It's also required for the :SnipMateOpenSnippetFiles command.

Remember to run :helptags ALL once your Vim has loaded SnipMate!

Using SnipMate

Install and create some snippets (see :h SnipMate-snippets). Then type in the trigger for one in the correct filetype and hit the expansion key (by default bound to <Tab>).

FAQ

SnipMate doesn't work / My snippets aren't triggering

Try all of the following:

• Check that SnipMate is loaded. This can be done by looking for <Plug>snipMateTrigger and similar maps in the output of :imap. Additionally make sure either <Plug>snipMateTrigger or <Plug>snipMateNextOrTrigger is mapped to the key you expect.

• Check that the snippets file you mean to use exists, and that it contains the snippet you're trying to expand.

• Check that your snippets file is located inside a foo/snippets directory, where foo is a path listed in your runtimepath.

• Check that your snippets file is in scope by either the filetype matching the path of the snippet file or the scope explicitly loaded.

• Check if any snippets from your snippets file are available. This can be done with the "show available snips" map, by default bound to <C-R><Tab> in insert mode.

If all of the above check out, please open an issue stating your Vim version, a sample snippet, and a description of exactly what happens when you try to trigger a snippet.

How does SnipMate determine which snippets to load? How can I separate, for example, my Rails snippets from my Ruby snippets?

Primarily SnipMate looks at the 'filetype' and 'syntax' settings. Taking "scopes" from these options, it looks in each snippets/ directory in 'runtimepath' for files named scope.snippets, scope/*.snippets, or scope_*.snippets.

However we understand this may not allow for the flexibility desired by some languages. For this we provide two options: scope aliases and the :SnipMateLoadScope command. Scope aliases simply say "whenever this scope is loaded, also load this other scope:

let g:snipMate = get(g:, 'snipMate', {}) " Allow for vimrc re-sourcing
let g:snipMate.scope_aliases = {}
let g:snipMate.scope_aliases['ruby'] = 'ruby,rails'

will load the ruby-rails scope whenever the ruby scope is active. The :SnipMateLoadScope foo command will always load the foo scope in the current buffer. The vim-rails plugin automatically does :SnipMateLoadScope rails when editing a Rails project for example.

What are the snippet parser versions and what's the difference between them?

Originally SnipMate used regex to parse a snippet. Determining where stops were, what the placeholders were, where mirrors were, etc. were all done with regex. Needless to say this was a little fragile. When the time came for a rewritten parser, some incompatibilities were a little necessary. Rather than break everyone's snippets everywhere, we provided both the new (version 1) and the old (version 0) and let the user choose between them.

Version 0 is considered legacy and not a lot of effort is going to go into improving or even maintaining it. Version 1 is the future, and one can expect new features to only exist for version 1 users. A full list of differences can be found in the docs at :h SnipMate-parser-versions.

Release Notes

Some changes listed here were contributed by non-maintainers. A full list can be found at Contributors.md.

Current

• Make tlib an optional dependency.
• Add SnipLookupPre and SnipLookupPost autocommand events
• Make version 1 of the snippet parser the default with no message

0.90 - 2023-12-29

• Remove empty lines at the end of a ${VISUAL} expansion
• Fix code for opening folds when expanding a snippet
• Deprecate legacy snippet parser
• Fix jumps when &sel == 'exclusive'

0.89 - 2016-05-29

• Various regex updates to legacy parser
• Addition of double bang syntax to completely remove a snippet from lookup
• Group various SnipMate autocommands
• Support setting 'shiftwidth' to 0
• Parser now operates linewise, adding some flexibility
• Mirror substitutions are more literal
• Mirror length is calculated correctly when substitutions occur

0.88 - 2015-04-04

• Implement simple caching

• Remove expansion guards

• Add :SnipMateLoadScope command and buffer-local scope aliases

• Load <scope>_*.snippets files

• Use CursorMoved autocmd events entirely

• The nested branch has been merged

  • A new snippet parser has been added. The g:snipmate.version as well as version lines in snippet files determines which is used
  • The new parser supports tab stops placed within placeholders, substitutions, non-consecutive stop numbers, and fewer ambiguities
  • The stop jumping code has been updated
  • Tests have been added for the jumping code and the new parser

• The override branch has been merged

  • The g:snipMate.override option is added. When enabled, if two snippets share the same name, the later-loaded one is kept and the other discarded
  • Override behavior can be enabled on a per-snippet basis with a bang (!) in the snippet file
  • Otherwise, SnipMate tries to preserve all snippets loaded

• Fix bug with mirrors in the first column

• Fix bug with tabs in indents (#143)

• Fix bug with mirrors in placeholders

• Fix reading single snippet files

• Fix the use of the visual map at the end of a line

• Fix expansion of stops containing only the zero tab stop

• Remove select mode mappings

• Indent visual placeholder expansions and remove extraneous lines (#177 and #178)

0.87 - 2014-01-04

• Stop indenting empty lines when expanding snippets
• Support extends keyword in .snippets files
• Fix visual placeholder support
• Add zero tabstop support
• Support negative 'softtabstop'
• Add g:snipMate_no_default_aliases option
• Add snipMateTrigger for triggering an expansion inside a snippet
• Add snipMate#CanBeTriggered() function