336 lines
15 KiB
Plaintext
336 lines
15 KiB
Plaintext
*buffergator.txt* Buffer indexing and navigation plugin.
|
|
|
|
===============================================================================
|
|
*buffergator* *buffergator-contents*
|
|
CONTENTS~
|
|
|
|
1. Introduction ........................... |buffergator-introduction|
|
|
2. Commands ............................... |buffergator-commands|
|
|
3. Key Mappings (Global) .................. |buffergator-global-keys|
|
|
4. Key Mappings (Buffer Catalog) .......... |buffergator-buffer-keys|
|
|
5. Key Mappings (Tab Page Catalog) ........ |buffergator-tabpage-keys|
|
|
6. Options and Settings ................... |buffergator-options|
|
|
|
|
===============================================================================
|
|
*buffergator-introduction*
|
|
INTRODUCTION~
|
|
|
|
Buffergator is a plugin for listing, navigating between, and selecting buffers
|
|
to edit. Upon invocation (using the command, ":BuffergatorOpen" or
|
|
"BuffergatorToggle", or the provided key mapping, "<Leader>b"), a "catalog" of
|
|
listed buffers are displayed in a separate new window split (vertical or
|
|
horizontal, based on user options; default = vertical). From this "buffer
|
|
catalog", a buffer can be selected and opened in an existing window, a new
|
|
window split (vertical or horizontal), or a new tab page.
|
|
|
|
Selected buffers can be "previewed", i.e. opened in a window or tab page, but
|
|
with focus remaining in the buffer catalog. Even better, you can "walk" up and
|
|
down the list of buffers shown in the catalog by using <C-N> (or <SPACE>) /
|
|
<C-P> (or <C-SPACE>). These keys select the next/previous buffer in succession,
|
|
respectively, opening it for preview without leaving the buffer catalog
|
|
viewer.
|
|
|
|
Buffergator also provides a way to list tab pages and buffers associated with
|
|
windows in tab pages (the "tab page catalog", which can be invoked using the
|
|
command ":BuffergatorTabsOpen" or the provided key mapping, "<Leader>to").
|
|
|
|
By default, Buffergator provides global key maps that invoke its main
|
|
commands: "<Leader>b" to open and "<Leader>B" to close the buffer catalog, and
|
|
"<Leader>to" to open and "<Leader>tc" to close the tab page catalog. If you
|
|
prefer to map other keys, or do not want any keys mapped at all, set
|
|
"g:buffergator_suppress_keymaps" to 1 in your $VIMRUNTIME.
|
|
|
|
===============================================================================
|
|
*buffergator-commands*
|
|
COMMANDS~
|
|
|
|
These following commands are provided globally by Buffergator:
|
|
|
|
:BuffergatorOpen
|
|
Open the buffer catalog, or go to it if it is already open.
|
|
|
|
:BuffergatorClose
|
|
Close the buffer catalog if it is already open.
|
|
|
|
:BuffergatorToggle
|
|
Open the buffer catalog if it is closed, or close it if
|
|
it is already open.
|
|
|
|
:BuffergatorTabsOpen
|
|
Open the tab page catalog, or go to it if it is already open.
|
|
|
|
:BuffergatorTabsClose
|
|
Close the tab page catalog if it is already open.
|
|
|
|
:BuffergatorTabsToggle
|
|
Open the tab page catalog if it is closed, or close it if
|
|
it is already open.
|
|
|
|
===============================================================================
|
|
*buffergator-global-keys*
|
|
KEY MAPPINGS (GLOBAL)~
|
|
|
|
Unless "g:buffergator_suppress_keymaps" is set to 1, then the following
|
|
key mappings are defined:
|
|
|
|
<Leader>b Invokes ":BuffergatorOpen": open the buffer catalog, or go
|
|
to it if it is already open.
|
|
|
|
<Leader>B Invokes ":BuffergatorClose": close the buffer catalog.
|
|
|
|
<Leader>to Invokes ":BuffergatorTabsOpen": open the tab page catalog,
|
|
or go to it if it is already open.
|
|
|
|
<Leader>tc Invokes ":BuffergatorTabsClose": close the tab page
|
|
catalog.
|
|
|
|
[b, <M-B> Invokes ":BuffergatorMruCyclePrev": cycle to an older
|
|
buffer in the most-recently used (MRU) buffer list.
|
|
most-recently used buffer. If
|
|
"g:buffergator_mru_cycle_loop" is set to 1 (default), then
|
|
this will loop, i.e. returning to the initial buffer after
|
|
reaching the oldest buffer.
|
|
|
|
]b, <M-S-B> Invokes ":BuffergatorMruCycleNext": cycle to a newer
|
|
buffer in the most-recently used (MRU) buffer list.
|
|
most-recently used buffer. If
|
|
"g:buffergator_mru_cycle_loop" is set to 1 (default), then
|
|
this will loop, i.e. returning to the oldest buffer after
|
|
reaching the newest buffer.
|
|
|
|
===============================================================================
|
|
*buffergator-buffer-keys*
|
|
KEY MAPPINGS (BUFFER CATALOG)~
|
|
|
|
Invoking Buffergator results in the listed buffers being displayed in a
|
|
special Buffergator window, which is referred to as a "buffer catalog viewer".
|
|
The following key mappings are available when in the viewer.
|
|
|
|
-------------------------------------------------------------------------------
|
|
Catalog Management~
|
|
|
|
cs Cycle through sort regimes.
|
|
cd Cycle through display regimes.
|
|
cp Toggle showing full paths (only "basename" display regime)
|
|
cw Cycle through window (viewport) split modes.
|
|
cq Cycle through quit (autodismiss-on-select) policies.
|
|
r Update (rebuild/refresh) index.
|
|
d Delete the selected buffer.
|
|
D Unconditionally delete the selected buffer.
|
|
x Wipe the selected buffer.
|
|
X Unconditionally wipe the selected buffer.
|
|
q Quit the index/catalog window.
|
|
|
|
-------------------------------------------------------------------------------
|
|
Open Selected Buffer~
|
|
|
|
The following keys all open the currently-selected buffer and switch focus to
|
|
it. If the key presses are preceded by a number, then the buffer with that
|
|
number will be selected and opened instead of the current buffer. The catalog
|
|
buffer will be closed if 'g:buffergator_autodismiss_on_select' evaluates to
|
|
true; otherwise it will be kept open.
|
|
|
|
<CR>, o Open the currently-selected buffer (or, if [count] is
|
|
given, buffer with number [count]), in previous window.
|
|
s Open the currently-selected buffer (or, if [count] is
|
|
given, buffer with number [count]), in a new vertical
|
|
split.
|
|
<C-V> As above (compatibility with Ctrl-P/Command-T)
|
|
i Open the currently-selected buffer (or, if [count] is
|
|
given, buffer with number [count]), in a new split.
|
|
<C-S> As above (compatibility with Ctrl-P/Command-T)
|
|
t Open the currently-selected buffer (or, if [count] is
|
|
given, buffer with number [count]), in a new tab page.
|
|
<C-T> As above (compatibility with Ctrl-P/Command-T)
|
|
|
|
-------------------------------------------------------------------------------
|
|
Preview Selected Buffer~
|
|
|
|
The following keys all open the currently-selected buffer, but retain focus on
|
|
the catalog viewer. If the key presses are preceded by a number, than the
|
|
buffer with that number will be opened.
|
|
|
|
O, go Preview the currently-selected buffer (or, if [count] is
|
|
given, buffer with number [count]), in the previous
|
|
window.
|
|
S, gs Preview the currently-selected buffer (or, if [count] is
|
|
given, buffer with number [count]), is a new vertical
|
|
split.
|
|
I, gi Preview the currently-selected buffer (or, if [count] is
|
|
given, buffer with number [count]), in a new split
|
|
T Preview the currently-selected buffer (or, if [count] is
|
|
given, buffer with number [count]), in a new tab
|
|
page.
|
|
<SPACE>, <C-N> Go to the next buffer entry (or, if [count] is
|
|
given, buffer with number [count]), and preview it in the
|
|
previous window.
|
|
<C-SPACE>, <C-P> Go to the previous buffer entry (or, if [count] is
|
|
given, buffer with number [count]), and preview it in the
|
|
previous window.
|
|
|
|
-------------------------------------------------------------------------------
|
|
Open and Switch Focus to Selected Buffer~
|
|
|
|
The following keys all open the currently-selected buffer and switch focus to
|
|
it, keeping the catalog viewe open, regardless of the
|
|
'g:buffergator_autodismiss_on_select' setting. If the key presses are preceded
|
|
by a number, than the buffer with that number will be opened.
|
|
|
|
po Open the currently-selected buffer (or, if [count] is
|
|
given, buffer with number [count]), in the previous
|
|
window, and switch focus to it, keeping the catalog
|
|
viewer open.
|
|
ps Open the currently-selected buffer (or, if [count] is
|
|
given, buffer with number [count]), is a new vertical
|
|
split, and switch focus to it, keeping the catalog
|
|
viewer open.
|
|
pi Open the currently-selected buffer (or, if [count] is
|
|
given, buffer with number [count]), in a new split,
|
|
and switch focus to it, keeping the catalog
|
|
viewer open.
|
|
|
|
-------------------------------------------------------------------------------
|
|
Go to Existing Viewport Showing Buffer~
|
|
|
|
The following keys will try to find the selected buffer in an existing
|
|
viewport (whether on the current tab page or another). If the key presses are
|
|
preceded by a number, then the buffer with that number will be the target
|
|
buffer.
|
|
|
|
eo If currently-selected buffer (or, if [count] is
|
|
given, buffer with number [count]), is showing in an existing
|
|
viewport on this or any other tab page, go to it;
|
|
otherwise show it in the previous window.
|
|
es If currently-selected buffer (or, if [count] is
|
|
given, buffer with number [count]), is showing in an existing
|
|
viewport on this or any other tab page, go to it;
|
|
otherwise show it in a new vertical split.
|
|
ei If currently-selected buffer (or, if [count] is
|
|
given, buffer with number [count]), is showing in an existing
|
|
viewport on this or any other tab page, go to it;
|
|
otherwise show it in a new horizontal split.
|
|
et If currently-selected buffer (or, if [count] is
|
|
given, buffer with number [count]), is showing in an existing
|
|
viewport on this or any other tab page, go to it;
|
|
otherwise show it in a new tab page.
|
|
E If currently-selected buffer (or, if [count] is
|
|
given, buffer with number [count]), is showing in an existing
|
|
viewport on this or any other tab page, go to it;
|
|
otherwise do nothing.
|
|
|
|
-------------------------------------------------------------------------------
|
|
Window Control~
|
|
|
|
A Zoom/unzoom window, expanding to full height (if
|
|
horizontally split) or full width (if vertically split)
|
|
|
|
===============================================================================
|
|
*buffergator-tabpage-keys*
|
|
KEY MAPPINGS (TAB PAGE CATALOG)~
|
|
|
|
-------------------------------------------------------------------------------
|
|
Catalog Management~
|
|
|
|
cd Cycle through display regimes.
|
|
r Update (rebuild/refresh) index.
|
|
q Quit the index/catalog window.
|
|
|
|
-------------------------------------------------------------------------------
|
|
Open Selected Tab Page or Tab Page Window~
|
|
|
|
The following keys all open the currently-selected tab page or window.
|
|
|
|
<CR>, o Open the currently-selected tab page or window.
|
|
<SPACE> Select the next tab page entry.
|
|
<C-SPACE> Select the previous tab page entry.
|
|
<C-N> Select the next tab page window entry.
|
|
<C-P> Select the previous tab page window entry.
|
|
|
|
-------------------------------------------------------------------------------
|
|
Window Control~
|
|
|
|
A Zoom/unzoom window, expanding to full height (if
|
|
horizontally split) or full width (if vertically split)
|
|
|
|
|
|
===============================================================================
|
|
*buffergator-options*
|
|
OPTIONS AND SETTINGS~
|
|
|
|
The following options can be used to customize the behavior of this plugin:
|
|
|
|
g:buffergator_viewport_split_policy~
|
|
Default: "L"
|
|
Determines how a new Buffergator window will be opened. Can be one of the
|
|
following values:
|
|
"L" : vertical left (full screen height)
|
|
"R" : vertical right (full screen height)
|
|
"T" : horizontal top (full screen width)
|
|
"B" : horizontal bottom (full screen width)
|
|
|
|
g:buffergator_autodismiss_on_select~
|
|
Default: 1
|
|
If true, then selection an entry with <CR> will close the catalog. Otherwise,
|
|
catalog stays open. Default is 1.
|
|
|
|
g:buffergator_autoexpand_on_split~
|
|
Default: 1
|
|
If true and running in GUI mode, then the application screen will be expanded
|
|
to accommodate the Buffergator window.
|
|
|
|
g:buffergator_autoupdate~
|
|
Default: 0
|
|
If true, then the Buffergator window will be updated when the buffer list
|
|
changes.
|
|
|
|
g:buffergator_split_size~
|
|
Default: 40
|
|
If greater than 0, this will be the width of the Buffergator window in any
|
|
vertical splitting mode, or its height in any horizontal splitting mode.
|
|
|
|
g:buffergator_vsplit_size~
|
|
Default: 40
|
|
If greater than 0, this will be the width of the Buffergator window in
|
|
any vertical splitting mode.
|
|
|
|
g:buffergator_hsplit_size~
|
|
Default: 20
|
|
If greater than 0, this will be the height of the Buffergator window in
|
|
any horizontal splitting mode.
|
|
|
|
g:buffergator_sort_regime~
|
|
Default: "bufnum"
|
|
Sets the default sort regime for buffer listing:
|
|
"bufnum" : sort by buffer number [default]
|
|
"basename": sort by buffer file basename (followed by directory)
|
|
"filepath": sort by full buffer filepath
|
|
"extension": sort by buffer filename extension (followed by full
|
|
filepath)
|
|
"mru": sort by most recently used
|
|
|
|
g:buffergator_display_regime~
|
|
Default: "basename"
|
|
Sets the default display regime for buffer listing:
|
|
"basename": display buffer basename first,
|
|
followed by directory [default]
|
|
"filepath": display full buffer filepath
|
|
"bufname": display buffer name
|
|
|
|
g:buffergator_show_full_directory_path~
|
|
Default: 1
|
|
If true, then show the full path of each buffer. Otherwise, show the
|
|
relative path.
|
|
Only relevant when the display regime is "basename".
|
|
|
|
g:buffergator_suppress_keymaps~
|
|
Default: 0
|
|
If true, then Buffergator will not automatically map "<Leader>b" to
|
|
open the Buffergator catalog and "<Leader>B" to close it.
|
|
|
|
g:buffergator_mru_cycle_local_to_window~
|
|
Default: 1
|
|
If true, then the most recently used list will include only buffers
|
|
within the window. Otherwise, it will incude all buffers.
|
|
|
|
vim:tw=78:ts=8:ft=help:norl:
|