*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, "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 (or ) / (or ). 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, "to"). By default, Buffergator provides global key maps that invoke its main commands: "b" to open and "B" to close the buffer catalog, and "to" to open and "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: b Invokes ":BuffergatorOpen": open the buffer catalog, or go to it if it is already open. B Invokes ":BuffergatorClose": close the buffer catalog. to Invokes ":BuffergatorTabsOpen": open the tab page catalog, or go to it if it is already open. tc Invokes ":BuffergatorTabsClose": close the tab page catalog. [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, 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. , 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. 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. 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. 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. , Go to the next buffer entry (or, if [count] is given, buffer with number [count]), and preview it in the previous window. , 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. , o Open the currently-selected tab page or window. Select the next tab page entry. Select the previous tab page entry. Select the next tab page window entry. 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 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 "b" to open the Buffergator catalog and "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: