Getting started with Vim

Update: This plugin is now contained in its own repository at https://github.com/ledger/vim-ledger. The files in contrib/vim are outdated.

---

Ledger's use of plain-text files for input is one of its great strengths, but it also means that, unless you have tools to help, entering that data in a text editor can be a very time-consuming manual process. It's therefore worthwhile finding out what can be done in your editor to streamline the creation of Ledger entries.

This page is intended as a place to put notes for those who know vim, but are not necessarily vim super-gurus, on how to use Vim with Ledger.

The Ledger source code comes with a contrib/vim/ directory containing some useful Vim plugins created by Wolfgang Oertl, Stefan Karrmann and Johann Klähn. You can copy the contents into your .vim directory, or, if you use the popular pathogen plugin, into a bundle/ledger directory.

Then add the following to your .vimrc:

 au BufNewFile,BufRead *.ldg,*.ledger setf ledger | comp ledger

and, if you don't already have them:

filetype plugin indent on
syntax on

Vim should now do syntax highlighting on your Ledger files, assuming they have a .ldg or .ledger extension. It will also 'fold' them so that each entry is represented by a single line. You can open and close a single entry to see the details using 'zo' and 'zc' - see :h fold for more information on folding. A quick note: metadata is only recognised as such and nicely coloured if you have at least two spaces before the semicolon.

You also get auto-completion on account names using Ctrl-X Ctrl-O (<C-X><C-O> in vim parlance). If you have an account called Assets:Bank:Checking, you can find and insert it by typing As:B:Ch<C-X><C-O>. Saves typing, and reduces errors.

But what about creating an entry in the first place? One option for this is the SnipMate plugin, which lets you create TextMate-style snippets, where you enter a few characters and hit <tab> to convert them into a full snippet. (See the screencast for a demo).

You can, for example, create a snippet for Ledger files that, when you type ent<tab>, will expand into an entry with today's date, the cursor positioned in the right place to enter further details, and you can then tab to the accounts, the values etc.

To do this, create a ledger.snippets file in your snippets directory containing the following:

snippet ent
    `system("date +%Y/%m/%d")` ${1:transaction}
        ${2:account}	${3:value}
        ${4}
endsnippet

Note: Snippets require the lines after the 'snippet' line to begin with a tab, which, of course, isn't visible above. You can add any extra spaces you want on each line after the tab.

You can tailor this to your needs. If you're experimenting with it, the command

:call ReloadAllSnippets()

may be useful!