Vim Bookmarks

A plugin to annotate and bookmark lines

View the Project on GitHub MattesGroeger/vim-bookmarks

Introduction

This vim plugin allows toggling bookmarks per line. A quickfix window gives access to all bookmarks. Annotations can be added as well. These are special bookmarks with a comment attached. They are useful for preparing code reviews. All bookmarks will be restored on the next startup.

Preview

Features

Installation

Before installation, please check your Vim supports signs by running :echo has('signs'). 1 means you're all set; 0 means you need to install a Vim with signs support. If you're compiling Vim yourself you need the 'big' or 'huge' feature set. MacVim supports signs.

Use your favorite plugin manager:

Usage

After installation you can directly start using it. You can do this by either using the default shortcuts or the commands:

Action Shortcut Command
Add/remove bookmark at current line mm :ToggleBookmark
Add/edit/remove annotation at current line mi :Annotate <TEXT>
Jump to next bookmark in buffer mn :NextBookmark
Jump to previous bookmark in buffer mp :PrevBookmark
Show all bookmarks ma :ShowAllBookmarks
Clear bookmarks in current buffer only mc :ClearBookmarks
Clear bookmarks in all buffers mx :ClearAllBookmarks
Save all bookmarks to a file :SaveBookmarks <FILE_PATH>
Load bookmarks from a file :LoadBookmarks <FILE_PATH>

You can change the shortcuts as you like, just read on...

Customization

Key Bindings

You can overwrite any of the default mappings. Just put the following into your ~/.vimrc and adjust as you like:

nmap <Leader><Leader> <Plug>ToggleBookmark
nmap <Leader>i <Plug>Annotate
nmap <Leader>a <Plug>ShowAllBookmarks
nmap <Leader>j <Plug>NextBookmark
nmap <Leader>k <Plug>PrevBookmark
nmap <Leader>c <Plug>ClearBookmarks
nmap <Leader>x <Plug>ClearAllBookmarks

Colors

Overwrite the default hightlight groups by adding this to your colorscheme or .vimrc:

highlight BookmarkSign ctermbg=whatever ctermfg=whatever
highlight BookmarkAnnotationSign ctermbg=whatever ctermfg=whatever
highlight BookmarkLine ctermbg=whatever ctermfg=whatever
highlight BookmarkAnnotationLine ctermbg=whatever ctermfg=whatever

Options

Put any of the following options into your ~/.vimrc in order to overwrite the default behaviour.

Option Default Description
let g:bookmark_sign = '>>' Sets bookmark icon for sign column
let g:bookmark_annotation_sign = '##' Sets bookmark annotation icon for sign column
let g:bookmark_auto_save = 0 1 Enables/disables automatic saving for bookmarks
let g:bookmark_auto_save_file = '/bookmarks' ~/.vim-bookmarks Sets file for auto saving
let g:bookmark_highlight_lines = 1 0 Enables/disables line highlighting
let g:bookmark_show_warning = 0 1 Enables/disables warning when clearing all bookmarks

FAQ

Why are the colours in the sign column weird?

Your colorscheme is configuring the SignColumn highlight group weirdly. To change that add this to your .vimrc: highlight SignColumn ctermbg=whatever.

What happens if I also use another plugin which uses signs (e.g. Syntastic)?

Vim only allows one sign per line. Therefore bookmarks will override any existing sign. When removing the bookmark the original sign will show up again. In other words vim-bookmarks won't remove another plugin's signs.

Why aren't any signs showing at all?

Make sure your vim supports signs: :echo has('signs') should give 1

Changelog

See the release page for all changes.

Credits & Contribution

This plugin was developed by Mattes Groeger under the MIT License. Pull requests are very welcome.

The following plugins were a great inspiration to me: