mirror of
https://github.com/SpaceVim/SpaceVim.git
synced 2025-01-24 06:10:05 +08:00
357 lines
12 KiB
Plaintext
357 lines
12 KiB
Plaintext
*bookmarks.txt* A Vim plugin for using line-based bookmarks.
|
|
|
|
|
|
Vim Bookmarks
|
|
|
|
|
|
Author: Mattes Groeger <http://blog.mattes-groeger.de/>
|
|
Plugin Homepage: <https://github.com/MattesGroeger/vim-bookmarks>
|
|
|
|
===============================================================================
|
|
CONTENTS *BookmarksContents*
|
|
|
|
1. Introduction ................. |BookmarksIntroduction|
|
|
2. Installation ................. |BookmarksInstallation|
|
|
3. Usage ........................ |BookmarksUsage|
|
|
4. Commands ..................... |BookmarksCommands|
|
|
5. Customisation ................ |BookmarksCustomisation|
|
|
6. Extending .................... |BookmarksExtening|
|
|
7. Unite Integration ............ |BookmarksUniteIntegration|
|
|
8. CtrlP Integration ............ |BookmarksCtrlPIntegration|
|
|
9. FAQ .......................... |BookmarksFAQ|
|
|
|
|
===============================================================================
|
|
1. INTRODUCTION *BookmarksIntroduction*
|
|
*Bookmarks*
|
|
|
|
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.
|
|
|
|
===============================================================================
|
|
2. INSTALLATION *BookmarksInstallation*
|
|
|
|
Use your favorite plugin manager:
|
|
|
|
Pathogen:
|
|
>
|
|
git clone https://github.com/MattesGroeger/vim-bookmarks.git \
|
|
~/.vim/bundle/vim-bookmarks
|
|
<
|
|
|
|
Vundle:
|
|
1. Add Plugin 'MattesGroeger/vim-bookmarks' to .vimrc
|
|
2. Run :PluginInstall
|
|
|
|
NeoBundle:
|
|
1. Add NeoBundle 'MattesGroeger/vim-bookmarks' to .vimrc
|
|
2. Run :NeoBundleInstall
|
|
|
|
vim-plug:
|
|
1. Add Plug 'MattesGroeger/vim-bookmarks' to .vimrc
|
|
2. Run :PlugInstall
|
|
|
|
===============================================================================
|
|
3. USAGE *BookmarksUsage*
|
|
|
|
You don't have to do anything: it just works.
|
|
|
|
===============================================================================
|
|
4. COMMANDS *BookmarksCommands*
|
|
|
|
Commands for using Bookmarks
|
|
|
|
:BookmarkToggle *:BookmarkToggle*
|
|
Add or remove bookmark at current line
|
|
|
|
:BookmarkAnnotate <TEXT> *:BookmarkAnnotate*
|
|
Add/edit/remove annotation at current line
|
|
|
|
:BookmarkNext *:BookmarkNext*
|
|
Jump to the next bookmark downwards
|
|
|
|
:BookmarkPrev *:BookmarkPrev*
|
|
Jump to the next bookmark upwards
|
|
|
|
:BookmarkShowAll *:BookmarkShowAll*
|
|
Show bookmarks across all buffers in new window (toggle)
|
|
|
|
:BookmarkClear *:BookmarkClear*
|
|
Removes bookmarks for current buffer
|
|
|
|
:BookmarkClearAll *:BookmarkClearAll*
|
|
Removes bookmarks for all buffer
|
|
|
|
:BookmarkMoveUp [<COUNT>] *:BookmarkMoveUp*
|
|
Move up the bookmark at current line by the specified amount of lines
|
|
(default: 1)
|
|
|
|
:BookmarkMoveDown [<COUNT>] *:BookmarkMoveDown*
|
|
Move down the bookmark at current line by the specified amount of lines
|
|
(default: 1)
|
|
|
|
:BookmarkMoveToLine <LINE> *:BookmarkMoveToLine*
|
|
Move the bookmark at current line to the specified <LINE>
|
|
|
|
:BookmarkSave <FILE_PATH> *:BookmarkSave*
|
|
Saves all bookmarks to a file so you can load them back in later
|
|
|
|
:BookmarkLoad <FILE_PATH> *:BookmarkLoad*
|
|
Loads bookmarks from a file (see :BookmarkSave)
|
|
|
|
===============================================================================
|
|
5. CUSTOMISATION *BookmarksCustomisation*
|
|
|
|
You can customise:
|
|
|
|
- The sign column's colours
|
|
- The signs' colours and symbols
|
|
- Line highlights
|
|
- Key mappings
|
|
- Whether or not line highlighting is on (defaults to off)
|
|
- Whether to close bookmarks split when jumping to a bookmark or not.
|
|
|
|
Please note that vim-bookmarks won't override any colours or highlights you've
|
|
set in your colorscheme.
|
|
|
|
SIGN COLUMN
|
|
|
|
The background colour of the sign column is controlled by the |hlSignColumn|
|
|
highlight group. This will be either set in your colorscheme or Vim's default.
|
|
|
|
To find out where it's set, and to what it's set, use:
|
|
>
|
|
:verbose highlight SignColumn
|
|
<
|
|
|
|
To change your sign column's appearance, update your colorscheme or |vimrc|
|
|
like this:
|
|
|
|
Desired appearance Command ~
|
|
Same as line number column highlight clear SignColumn
|
|
User-defined (terminal Vim) highlight SignColumn ctermbg={whatever}
|
|
User-defined (graphical Vim) highlight SignColumn guibg={whatever}
|
|
|
|
SIGNS' COLOURS AND SYMBOLS
|
|
|
|
To customise the colours, set up the following highlight groups in your
|
|
colorscheme or |vimrc|:
|
|
>
|
|
BookmarkSign " the sign
|
|
BookmarkAnnotationSign " the annotation sign
|
|
<
|
|
|
|
You can either set these with `highlight BookmarkSign {key}={arg}...` or link
|
|
them to existing highlight groups with, say:
|
|
>
|
|
highlight link BookmarkSign Todo
|
|
<
|
|
|
|
To customise the symbols, add the following to your |vimrc|:
|
|
>
|
|
let g:bookmark_sign = '>>'
|
|
let g:bookmark_annotation_sign = '##'
|
|
<
|
|
|
|
LINE HIGHLIGHTS
|
|
|
|
Similarly to the signs' colours, set up the following highlight group in your
|
|
colorscheme or |vimrc|:
|
|
>
|
|
BookmarkLine " the highlighted line
|
|
BookmarkAnnotationLine " the highlighted annotation line
|
|
<
|
|
|
|
KEY MAPPINGS
|
|
|
|
To change the default keys:
|
|
>
|
|
nmap <Leader><Leader> <Plug>BookmarkToggle
|
|
nmap <Leader>i <Plug>BookmarkAnnotate
|
|
nmap <Leader>a <Plug>BookmarkShowAll
|
|
nmap <Leader>j <Plug>BookmarkNext
|
|
nmap <Leader>k <Plug>BookmarkPrev
|
|
nmap <Leader>c <Plug>BookmarkClear
|
|
nmap <Leader>x <Plug>BookmarkClearAll
|
|
|
|
" these will also work with a [count] prefix
|
|
nmap <Leader>kk <Plug>BookmarkMoveUp
|
|
nmap <Leader>jj <Plug>BookmarkMoveDown
|
|
nmap <Leader>g <Plug>BookmarkMoveToLine
|
|
<
|
|
|
|
To prevent any default mappings from being created (default: 0):
|
|
>
|
|
let g:bookmark_no_default_key_mappings = 1
|
|
<
|
|
|
|
MORE OPTIONS
|
|
|
|
Change the following options in your |vimrc| to customize the plugin behaviour.
|
|
|
|
Save/show bookmarks per working directory/project (default 0):
|
|
|
|
>
|
|
let g:bookmark_save_per_working_dir = 1
|
|
<
|
|
|
|
When this option is enabled, a file called `.vim-bookmarks` will be stored in
|
|
the current working directory whenever you create bookmarks. You should add this
|
|
file to your (global) `.gitignore` file so it doesn't get checked into version
|
|
control.
|
|
|
|
Enable bookmark management on a per buffer basis:
|
|
|
|
>
|
|
let g:bookmark_manage_per_buffer = 1
|
|
<
|
|
|
|
This will save and load the bookmarks file whenever the buffer changes (e.g.,
|
|
switching tabs/buffers). It makes most sense when g:bookmark_save_per_working_dir
|
|
is turned on as well, or when a customizing function is used.
|
|
|
|
Disable auto saving (default 1):
|
|
|
|
>
|
|
let g:bookmark_auto_save = 0
|
|
<
|
|
|
|
Change file for auto saving (default $HOME .'/.vim-bookmarks'):
|
|
|
|
>
|
|
let g:bookmark_auto_save_file = '/tmp/my_bookmarks'
|
|
<
|
|
|
|
Turn on line highlighting (default 0):
|
|
|
|
>
|
|
let g:bookmark_highlight_lines = 1
|
|
<
|
|
|
|
Turn off the warning when clearing all bookmarks (default 1):
|
|
|
|
>
|
|
let g:bookmark_show_warning = 0
|
|
<
|
|
|
|
Turn off the warning when toggling to clear a bookmark with annotation (default 1):
|
|
|
|
>
|
|
let g:bookmark_show_toggle_warning = 0
|
|
<
|
|
|
|
Turn on vertical line centering when jumping to bookmark (default 0):
|
|
|
|
>
|
|
let g:bookmark_center = 1
|
|
<
|
|
|
|
Automatically close bookmarks split when jumping to a bookmark (default 0):
|
|
|
|
>
|
|
let g:bookmark_auto_close = 1
|
|
<
|
|
|
|
Use the location list to show all bookmarks (default 0):
|
|
|
|
>
|
|
let g:bookmark_location_list = 1
|
|
|
|
|
|
You can disable Ctrlp by setting (default 0)
|
|
>
|
|
let g:bookmark_disable_ctrlp = 1
|
|
<
|
|
===============================================================================
|
|
6. EXTENDING *BookmarksExtending*
|
|
|
|
You can implement automatic switching of bookmarks file on your desired event.
|
|
To do so, use functions BookmarkSave, BookmarkLoad and BookmarkClearAll with
|
|
the last argument set to 1. This will suppress any messages and prompts these
|
|
functions normally issue. The BookmarkLoad function will return 1 to indicate
|
|
that file loading was successful, and 0 for failure. An example script using
|
|
this feature is located in the 'examples/bm-autoload-example.vim' file.
|
|
|
|
===============================================================================
|
|
7. Unite Integration *BookmarksUniteIntegration*
|
|
|
|
Unite is a multi-purpose user-interface plugin platform. vim-bookmarks provide
|
|
an Unite source called *vim_bookmarks* so users who use Unite will handle
|
|
bookmarks with the Unite interface. When showing all your bookmarks, Unite is
|
|
detected and the plugin will open ':Unite vim_bookmarks' instead of Vim's
|
|
quickfix window. Note that |g:bookmark_auto_close| is no longer applied, once
|
|
opened, the window is managed by Unite.
|
|
|
|
To set a global per-source context setting, that will apply to Unite's quickfix
|
|
source everytime it's opened, you can add this to your |vimrc|:
|
|
>
|
|
call unite#custom#profile('source/vim_bookmarks', 'context', {
|
|
\ 'winheight': 13,
|
|
\ 'direction': 'botright',
|
|
\ 'start_insert': 0,
|
|
\ 'keep_focus': 1,
|
|
\ 'no_quit': 1,
|
|
\ })
|
|
<
|
|
|
|
With the Unite interface, when you select bookmarks, you can perform the
|
|
following actions.
|
|
|
|
- Open the selected bookmarks in various ways (open in right, open in above,
|
|
open in new tab, etc.)
|
|
- Yank the informations of selected bookmarks (path and line number, the line
|
|
content, annotation, etc.)
|
|
- Highlight the lines of the selected bookmarks
|
|
- Replace the contents of selected bookmarks with vim-qfreplace
|
|
- Delete the selected bookmarks
|
|
- And more!
|
|
|
|
For more information about Unite, start reading |:Unite|.
|
|
|
|
https://github.com/Shougo/unite.vim
|
|
https://github.com/thinca/vim-qfreplace
|
|
|
|
===============================================================================
|
|
8. CtrlP Integration *BookmarksCtrlPIntegration*
|
|
|
|
ctrlp.vim is a Full path fuzzy file, buffer, mru, tag, ... finder for Vim.
|
|
|
|
Additionally, when showing all your bookmarks, CtrlP is detected and the plugin
|
|
will open *:CtrlPBookmark* instead of Vim's quickfix window. Note that
|
|
|g:bookmark_auto_close| is no longer applied. Once opened, the window is managed
|
|
by CtrlP.
|
|
|
|
With the CtrlP interface, when you select bookmarks, you can perform the
|
|
following actions:
|
|
|
|
* Open the selected bookmarks in various ways (open to the right, open above,
|
|
open in new tab, etc.)
|
|
* And more...
|
|
|
|
For more information about CtrlP start reading |CtrlP@en|.
|
|
|
|
https://github.com/ctrlpvim/ctrlp.vim
|
|
|
|
===============================================================================
|
|
9. FAQ *BookmarksFAQ*
|
|
|
|
a. Why are the colours in the sign column weird?
|
|
|
|
Your colorscheme is configuring the |hl-SignColumn| highlight group weirdly.
|
|
Please see |BookmarksCustomisation| on customising the sign column.
|
|
|
|
b. 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.
|
|
|
|
c. Why aren't any signs showing at all?
|
|
|
|
Make sure your vim supports signs. This should return "1":
|
|
>
|
|
:echo has('signs')
|
|
<
|
|
vim:ft=help:et:ts=2:sw=2:sts=2:norl
|