Vim-CtrlSpace

TL;DR

Vim-CtrlSpace is a great plugin that helps you to get more power from Vim while working with buffers, tabs, windows, and so on. It is meant to organize your Vim screen space and your workspace effectively. To accomplish that Vim-CtrlSpace introduces a concept of separated buffer lists per tab and provides a lot of power around that (buffer and file management, multiple workspaces stored on disk, fuzzy search, tab management, and more).

Its name follows the convention of naming similar plugins after their default mappings (like Command-T or CtrlP). Obviously, the plugin mapping is by default Ctrl + Space.

If you like the plugin please don't forget to add a star (:star:)! This will help me to estimate the plugin popularity and that way I will proceed better its further development :).

Demo

Here's a small demonstration. Viewing in HD advised!

The Demo has been recorded with:

a console Vim 7.4 (Menslo font)
a bit modified Seoul256 color scheme

following Vim-CtrlSpace settings in .vimrc:

  hi CtrlSpaceSelected term=reverse ctermfg=187  ctermbg=23  cterm=bold
  hi CtrlSpaceNormal   term=NONE    ctermfg=244  ctermbg=232 cterm=NONE
  hi CtrlSpaceFound    ctermfg=220  ctermbg=NONE cterm=bold

music: Professor Kliq - Curriculum Vitae

About

The Story

There are many ways of working with Vim. It's no so straight forward like in other editors. People often find their own methods of working with Vim and increasing their productivity. However, some settings and scenarios seem to be preffered rather than others. And that means also some common issues.

The main attitude is to combine buffers, split windows, and tabs effectively. In Vim, unlike in other editors, tabs are not tabs really. They are just containers for split windows, sometimes referred as viewports. The tab list - considered as a list of open files - buffers, is called a buffer list. Usually, it's not immediately visible but you can issue a command :ls to see it yourself.

Of course, there are many plugins allowing you to see, change, and manage buffers. In fact, Vim-CtrlSpace has been started as a set of improvements of a such existing plugin. It was named VIM bufferlist by Rob Lillack. That was a neat and tiny plugin (270 LOC), but a bit abandoned. Now, about 7 months later, Vim-CtrlSpace has about 2.5K LOC and still uses some code of that Rob's plugin :).

Characteristic Vim usage, exhibited by many Vim power users, is to treat tabs as units of work on different topics. If, for example, I work on a web application with User management, I can have a tab containing a User model and test files, perhaps a User controller file, and some view files. If it would be possible (actually in Vim-CtrlSpace it is!) I could name that tab Users. Then, if I move to, let's say Posts I can have similar set of open files in the next tab. That way I can go back and forward between these two concerns. In the third tab I could have e.g. config files, etc.

This approach works, and works very well. In fact, you can never touch the real buffer list down there. You can even disable so called hidden buffers to make sure you manage only what you see in tabs.

I've been working that way for a long time. However, there are some subtle issues behind the scene. The first one is the screen size. With this approach you are limited to the screen size. At some point the code in split windows doesn't fit those windows at all, even if you have a full HD screen with Vim maximized. The second issue is a lot of distraction. Sometimes you might want just to focus on a one particular file. To address that I have developed a tool called Vim-Maximizer. Vim-Maximizer allows you to temporarily maximize one split window, just by pressing F3 (by default). This can be seen in the demo movie above. That was cool, but still I needed something better, especially since I started working on 13-inch laptop...

And that was the moment when Vim-CtrlSpace came to play.

Vim-CtrlSpace Idea

First, I wanted a cool buffer list. Something neat and easy. MinibufExplorer and friends have some issues with unnamed buffers. Also, I have troubles when I have too many buffers open. The list gets longer and longer. A tool like CtrlP was helpful to some point (usually when I was looking for a buffer), but it doesn't show you all buffers available.

I started playing with Rob Lillack's VIM bufferlist and finally I've created a solution. I've introduced a concept of many buffer lists tightly coupled with tabs. That means each tab holds its own buffer list. Once a buffer is shown in the tab, the tab is storing it in its own buffer list. No matter in which window. It's just like having many windows related to the same concern, but without the need of split windows at all! Then you can forget the buffer (remove it from tab's buffer list), or perform many other actions. Of course, it's possible to access the main buffer list (the list of all open buffers) - in that way, you can easily add new friends to the current tab. It's also perfectly valid to have a buffer shared among many tabs at the same time (it will be listed on many lists). Similarly, you can have a buffer that is not connected to any particular tab. It's just a hidden buffer (not displayed at the moment), visible only in the all buffers list.

That was a breaking change. Next things are just consequences of that little invention. I've added a lot of buffer operations (opening, closing, renaming, etc), the ability of opening files (together with file operations too), fuzzy search through buffer lists and files, separate jump lists, search history, easy tab access (with full tab management and custom tab names), and last but not least, workspace management (saving to disk and loading). That means you can have plenty of named workspaces per project.

All those improvements let me to start using Vim-CtrlSpace instead of CtrlP or even NERDTree. But, of course, nothing stops you to combine all those plugins together, especially if you used to work with them. There are no inteferences, just some functionality doubling.

Installation

The plugin installation is really simple. You can use Vundle or Pathogen, or just clone the repository to your .vim directory. In case of Vundle, add:

Bundle "szw/vim-ctrlspace"

to your .vimrc.

If you want to increase plugin speed (e.g. fuzzy search), make sure you have decent Ruby bindings enabled in (compiled into) your Vim. The plugin will try to use your Ruby by default.

Usage

Status Line

Vim-CtrlSpace requires a status bar. If you are using a plugin customizing the status bar this could be a bit tricky. For example vim-airline plugin might require you to set: let g:airline_exclude_preview = 1 option and LightLine will require to use custom status line segments, provided by Vim-CtrlSpace API.

Status Line Symbols

Unicode Symbol	ASCII Symbol	Description
`▢`	`CS`	Vim-CtrlSpace symbol
`⊙`	`TAB`	Single Tab mode indicator
`∷`	`ALL`	All Tabs mode indicator
`○`	`ADD`	Add mode indicator
`⌕`	`*`	Preview mode indicator
`⋮ → ∙`	`LOAD`	Workspace mode (load)
`∙ → ⋮`	`SAVE`	Workspace mode (save)
`›_‹`	`[_]`	Search mode or search order
`₁²₃`	`123`	Order buffers by numbers (in Single Tab and All Tabs modes)
`авс`	`ABC`	Order buffers alphabetically (in Single Tab and All Tabs modes)

Tabline

Vim-CtrlSpace can set a custom tabline. If the proper option is enabled (g:ctrlspace_use_tabline), the plugin will set a custom tabline for you. The tabs in that tabline are displayed in the following way:

Unicode	`1`	`²`	`+`	`[`	`README.md`	`]`
ASCII	`1`	`:2`	`+`	`[`	`README.md`	`]`
Description	Tab number	Buffers count	Modified indicator	Opening bracket (only for buffer names)	Buffer or tab name	Closing bracket (only for buffer names)

If GUI tabs are detected, this option will also set the proper function to guitablabel.

Tab Management

Tabs in Vim-CtrlSpace (like in Vim) are groups of related buffers. The plugin lets you to perform many classic tab actions easily e.g. switching ([ and ]), moving (+ and -), closing (uppercase C), or renaming (=). The list of all tabs can be seen with l.

You can also create empty tabs (T) or copy them (Y). The latter action is useful if you want to split your tab (your group of buffers) into smaller ones. Referring to the demo example, the tab Users (holding model files, controller files and views) could be split into something like Users (models) and Users (views). Users (models) could then have model and controller files whereas Users (views) could be storing controller and view ones. With the help of tab copying (Y) all you need is to copy the Users tab, close superfluous buffers in each (lowercase c), and finally rename both (=). Of course, the split shown in that example might be a bit dummy but in a typical project there are a lot of natural splits, like for example, backend and frontend layers.

Project Root

The plugin requires a project root to work properly. If you open the plugin window for the first time it will try to find out the possible root directory. First, it starts in the Vim current working directory and check if there are so called root markers. The root markers are characteristic files or directories that are available in an exemplary project root directory, like e.g. .git or .hg directories. You can define them yourself in the g:ctrlspace_project_root_markers variable. If no markers found, the plugin will check if perhaps this directory is a known root. The known roots are those ones you provided (accepted) yourself when no markers were found. If the current directory cannot be proven as a project root, the algorithm will repeat the whole procedure in the parent one.

After checking all predecessors it will ask you to provide the root folder explicitly. After your acceptance that root folder will be stored pemanently in the .cs_cache file as serve as a known root later.

Main Modes

The plugin offers you a few modes. In a modal editor like Vim this should not fear you ;). I believe its modes are very simple to recognize and understand.

Moreover, buffers and workspaces listed in the plugin window can have additional indicators (following the item text):

Unicode Symbol	ASCII Symbol	Indicator
`+`	`+`	Item modified
`★`	`*`	Item visible (or active)

Simplified Key Diagram

This is a simplified diagram of key groups used in Vim-CtrlSpace modes.

Single Tab Mode

Unicode Symbol	ASCII Symbol
`⊙`	`TAB`

The first main mode is the Single Tab. In that mode, the plugin shows you only buffers related to the current tab. It's almost like a normal mode in Vim ;). It's like a root from you can follow many paths. Here's the full listing of full available keys:

Keys Reference

Group	Key	Action
Help	`?`	Toggles info about available keys (depends on space left in the status bar)
Opening	`Return`	Opens a selected buffer
	`Space`	Opens a selected buffer and stays in the Vim-CtrlSpace window
	`Tab`	Enters the Preview mode for selected buffer
	`v`	Opens selected buffer in a new vertical split
	`s`	Opens selected buffer in a new horizontal split
	`t`	Opens selected buffer in a new tab
Searching & sorting	`/`	Enters the Search mode
	`\`	Enters the Search mode in the Add (files) mode immediately (a shortcut for `A/`)
	`Ctrl + p`	Brings back the previous searched text
	`Ctrl + n`	Brings the next searched text - just the opposite to `Ctrl + p`
	`o`	Toggles the sorting order (chronological vs alphanumeric)
Tabs operations	`T`	Creates a new tab and stays in the plugin window
	`Y`	Copies (yanks) the current tab into a new one
	`0..9`	Jumps to the n-th tab (0 is for the 10th one)
	`-`	Moves the current tab to the left (decreases its number)
	`+`	Moves the current tab to the right (increases its number)
	`=`	Changes the tab name
	`_`	Removes a custom tab name
	`[`	Goes to the previous (left) tab
	`]`	Goes to the next (right) tab
Exiting	`Backspace`	Goes back (in this mode it will just close the plugin window)
	`q`, `Esc`, and `Ctrl + Space`	Closes the list * - depends on plugin settings
	`Q`	Quits Vim (but with a prompt if unsaved workspaces or tab buffers were found)
Moving	`j`	Moves the selection bar down
	`k`	Moves the selection bar up
	`J`	Moves the selection bar to the bottom of the list
	`K`	Moves the selection bar to the top of the list
	`p`	Moves the selection bar to the previous opened buffer
	`P`	Moves the selection bar to the previous opened buffer and opens it immediately
	`n`	Moves the selection bar to the next opened buffer (just the reverse of `p`)
	`Ctrl + f`	Moves the selection bar one screen down (just like standard Vim behavior)
	`Ctrl + b`	Moves the selection bar one screen up (just like standard Vim behavior)
	`Ctrl + d`	Moves the selection bar a half screen down (just like standard Vim behavior)
	`Ctrl + u`	Moves the selection bar a half screen up (just like standard Vim behavior)
Closing	`d`	Deletes the selected buffer (closes it)
	`D`	Closes all empty noname buffers
	`f`	Forgets the current buffer (make it a foreign (unrelated) to the current tab)
	`F`	Deletes (closes) all forgotten buffers (unrelated to any tab)
	`c`	Combines `c` and `d`. If the selected buffer is opened only in the current tab - `c` will close (delete) it. Otherwise it will just forget it (detach from the current tab)
	`C`	Closes the current tab, then performs `F` (closes forgotten buffers - probably these from that just closed tab) and `D` (closes empty nonames)
Disk operations	`e`	Edits a sibling of the selected buffer (it will create a new one if necessary)
	`E`	Explores a directory of the selected buffer
	`R`	Removes the selected buffer (file) entirely (from the disk too)
	`m`	Moves or renames the selected buffer (together with its file)
Mode changing	`a`	Toggles between Single Tab and All Tabs modes
	`A`	Enters the Add (file) mode
	`w`	Enters the Workspace mode
Workspace shortcuts	`S`	Saves the workspace immediately (or creates a new one if none)
Workspace shortcuts	`L`	Loads the last active workspace (if present)

All Tabs Mode

Unicode Symbol	ASCII Symbol
`∷`	`ALL`

This mode is almost identical to the Single Tab mode, except it shows you all available buffers (from all tabs and unrelated ones too). Some of keys presented in the Single Tab mode are not available here. The missing ones are f and c - as they are tightly coupled with the current tab.

Add Mode

Unicode Symbol	ASCII Symbol
`○`	`ADD`

The file mode, or the file append mode. It allows you to add a file (as a buffer) to the current tab. In other words, it opens files from the project root directory. Notice, only the project root directory is considered here. This will prevent you from accidental loading root of i.e. your home directory, as it would be really time consuming and rather pointless.

For the first time (or after some disk operations) the file list is populated with data. Sometimes, for a very large project this could be quite time consuming (I've noticed a lag for a project with over 2200 files). After that, the content of the project root directory is cached and available immediately. All the time you can force plugin to refresh the list with the r key.

Keys Reference

Group	Key	Action
Help	`?`	Toggles info about available keys (depends on space left in the status bar)
Opening	`Return`	Opens a selected file
	`Space`	Opens a selected file but stays in the Vim-CtrlSpace window
	`v`	Opens a selected file in a new vertical split
	`s`	Opens a selected file in a new horizontal split
	`t`	Opens a selected file in a new tab
Exiting	`Backspace`, `a`, and `A`	Goes back (here it will return to Single Tab or All Tabs mode)
	`q`, `Esc`, and `Ctrl + Space`	Closes the list * - depends on plugin settings
	`Q`	Quits Vim (but with a prompt if unsaved workspaces or tab buffers were found)
Tabs operations	`T`	Creates a new tab and stays in the plugin window
	`Y`	Copies (yanks) the current tab into a new one
	`0..9`	Jumps to the n-th tab (0 is for 10th one)
	`-`	Moves the current tab to the left (decreases its number)
	`+`	Moves the current tab to the right (increases its number)
	`=`	Changes the tab name
	`_`	Removes a custom tab name
	`[`	Goes to the previous (left) tab
	`]`	Goes to the next (right) tab
Searching	`/` and `\`	Enters the Search mode
	`Ctrl + p`	Brings back the previous searched text
	`Ctrl + n`	Brings the next searched text - just the opposite to `Ctrl + p`
Moving	`j`	Moves the selection bar down
	`k`	Moves the selection bar up
	`J`	Moves the selection bar to the bottom of the list
	`K`	Moves the selection bar to the top of the list
	`Ctrl + f`	Moves the selection bar one screen down (just like standard Vim behavior)
	`Ctrl + b`	Moves the selection bar one screen up (just like standard Vim behavior)
	`Ctrl + d`	Moves the selection bar a half screen down (just like standard Vim behavior)
	`Ctrl + u`	Moves the selection bar a half screen up (just like standard Vim behavior)
Closing	`C`	Closes the current tab, then closes forgotten buffers and empty nonames
Disk operations	`e`	Edits a sibling of the selected buffer (it will create a new one if necessary)
	`E`	Explores a directory of the selected buffer
	`r`	Refreshes the file list (forces reloading)
	`R`	Removes the selected file entirely
	`m`	Moves or renames the selected file
Mode changing	`w`	Enters the Workspace mode

Workspace Mode

Unicode Symbol	ASCII Symbol
`⋮ → ∙`	`LOAD`
`∙ → ⋮`	`SAVE`

The plugin allows you to save and load so called workspaces. A workspace is a set of opened windows, tabs, their names, and buffers. In fact, the word workspace can be considered as a synonym of a session in Vim-CtrlSpace.

The ability of having so many sessions available at hand creates a lot of interesting use cases! For example, you can have a workspace for each task or feature you are working on. It's very easy to switch from one workspace to another, thus this could be helpful with reviewing completed tasks and continuing work on an item after some period of time. Moreover, you can have special workspaces that are prepared to be appended to others. Consider, e.g. a Config workspace. Imagine, you have a separate workspace with the only one tab named Config and some config files opened there. You can easily append that workspace to you current or next ones, depending on your needs. That way you are able to group the common and repetative sets of files in just one place and reuse that group in many contexts.

In the Workspace mode Vim-CtrlSpace shows you available workspaces instead of buffers. By default this mode is displayed in the LOAD state. The second available state is SAVE.

Workspaces are saved in a file inside the project directory. Its name and path is determined by proper plugin configuration options (g:ctrlspace_workspace_file). If there are 2 or more split windows in a tab, they will be recreated as vertical splits while loading.

It's also possible to automatically load the last active workspace on Vim startup and save it active workspace on Vim exit. See g:ctrlspace_load_last_workspace_on_start and g:ctrlspace_save_workspace_on_exit for more details.

Keys Reference

Group	Key	Action
Help	`?`	Toggles info about available keys (depends on space left in the status bar)
Accepting	`Return`	Loads (or save) the selected workspace
Exiting	`Backspace`, `w`	Goes back (here it will return to Single Tab or All Tabs mode)
	`q`, `Esc`, and `Ctrl + Space`	Closes the list * - depends on settings
	`Q`	Quits Vim (but with a prompt if unsaved workspaces or tab buffers were found)
Workspace operations	`a`	Appends a selected workspace to the current one
	`s`	Toggles the workspace state from load or save (or backward)
	`S`	Saves the workspace immediately
	`L`	Loads the last active workspace (if present)
	`d`	Deletes the selected workspace
Moving	`j`	Moves the selection bar down
	`k`	Moves the selection bar up
	`J`	Moves the selection bar to the bottom of the list
	`K`	Moves the selection bar to the top of the list
	`Ctrl + f`	Moves the selection bar one screen down (just like standard Vim behavior)
	`Ctrl + b`	Moves the selection bar one screen up (just like standard Vim behavior)
	`Ctrl + d`	Moves the selection bar a half screen down (just like standard Vim behavior)
	`Ctrl + u`	Moves the selection bar a half screen up (just like standard Vim behavior)

Tablist Mode

Unicode Symbol	ASCII Symbol
`∘∘∘`	`TABS`

In this mode you can list all tabs. It is useful if the tabline too long to be rendered properly or it is just turned off via showtabline option.

Keys Reference

Group	Key	Action
Help	`?`	Toggles info about available keys (depends on space left in the status bar)
Opening and closing	`Return`	Opens a selected tab and enters the Single Tab mode
	`Tab`	Opens a selected tab and closes the plugin window
	`Space`	Opens a selected tab but stays in the Tablist mode
	`c`	Closes the selected tab, then closes forgotten buffers and empty nonames
Exiting	`Backspace`, `l`	Goes back (here it will return to Single Tab or All Tabs mode)
Exiting	`q`, `Esc`, and `Ctrl + Space`	Closes the list * - depends on plugin settings
Tabs operations	`-`	Moves the current tab backward (decreases its number)
	`+`	Moves the selected forward (increases its number)
	`=`	Changes the selected tab name
	`_`	Removes the selected tab name
	`[`	Goes to the previous tab
	`]`	Goes to the next tab
	`t`	Creates a new tab nexto to the current one
	`y`	Creates a copy of the current tab
Moving	`j`	Moves the selection bar down
	`k`	Moves the selection bar up
	`J`	Moves the selection bar to the bottom of the list
	`K`	Moves the selection bar to the top of the list
	`Ctrl + f`	Moves the selection bar one screen down (just like standard Vim behavior)
	`Ctrl + b`	Moves the selection bar one screen up (just like standard Vim behavior)
	`Ctrl + d`	Moves the selection bar a half screen down (just like standard Vim behavior)
	`Ctrl + u`	Moves the selection bar a half screen up (just like standard Vim behavior)

Auxiliary Modes

These modes are just blended into the main ones. They can be considered as special cases or states of the main ones.

Preview Mode

Unicode Symbol	ASCII Symbol
`⌕`	`*`

This mode applies to buffer-related modes: Single Tab and All Tabs. You can invoke the Preview mode by hitting the Tab key. Hitting Tab does almost the same as Space - it shows you the selected buffer, but unlike Space, that change of the target window content is not permanent. When you quit the plugin window, the old (previous) content of the target window is restored.

Also the jumps history remains unchanged and the selected buffer won't be added to the tab buffer list. In that way, you can just preview a buffer before actually opening it (with Space, Return, etc).

Those previewed files are marked on the list with the star symbol and the original content is marked with an empty star too:

Indicator	Unicode Symbol	ASCII Symbol
Previewed buffer	`★`	`*`
Original buffer	`☆`	`*`

Search Mode

Unicode Symbol	ASCII Symbol
`›_‹`	`[_]`

This mode is composed of two states or two phases. The first one is the entering phase. Technically, this is the extact Search mode. In the entering phase the following keys are available:

Keys Reference (entering phase)

Key	Action
`?`	Toggles info about available keys (depends on space left in the status bar)
`Return`	Closes the entering phase. Accepts the entered content.
`Backspace`	Removes the previouse entered character, or closes the entering phase if no character found.
`/`	Toggles the entering phase
`\`	Toggles the entering phase (only in the Add mode)
`a..z A..Z 0..9`	The charactes allowed in the entering phase

Besides the entering phase there is also a second state possible. That is the state of having a search query entered. The successfully entered query behaves just like a kind of sorting. In fact, it is just a kind of sorting and filtering function. So it doesn't impact on other modes except it narrows the result set.

It's worth to mention that in that mode the Backspace key removes the search query entirely.

Nop Mode

Nop (Non-Operational) mode happens when i.e. there are no items to show (empty list), or you are trying to type a Search query, and there are no results at all. That means the Nop can happen during the entering phase of the Search mode or in some other cases. Those other cases can occur, for example, when you have only not listed buffers available in the tab (like e.g. help window and some preview ones). As you will see, in such circumstances - that is outside the entering phase - there is a greater number of resque options available.

Nop (Search entering phase)

Key	Action
`?`	Toggles info about available keys (depends on space left in the status bar)
`Backspace`	Removes the previouse entered character, or closes the entering phase if no character found.
`Esc`*	Closes the list * - depends on settings

Nop (outside the entering phase)

Key	Action
`?`	Toggles info about available keys (depends on space left in the status bar)
`Backspace`	Deletes the search query
`q`, `Esc`, and `Ctrl + Space`	Closes the list * - depends on settings
`Q`	Quits Vim (but with a prompt if unsaved workspaces or tab buffers were found)
`a`	Toggles between Single Tab and All Tabs modes
`A`	Enters the Add (file) mode
`Ctrl + p`	Brings back the previous searched text
`Ctrl + n`	Brings the next searched text - just the opposite to `Ctrl + p`

Configuration

Vim-CtrlSpace has following configuration options. Almost all of them are declared as global variables and should be defined in your .vimrc file in the similar form:

let g:ctrlspace_foo_bar = 123

`g:ctrlspace_height`

Sets the minimal height of the plugin window. Default value: 1.

`g:ctrlspace_max_height`

Sets the maximum height of the plugin window. If 0 provided it uses 1/3 of the screen height. Default value: 0.

`g:ctrlspace_show_unnamed`

Adjusts the displaying of unnamed buffers. If you set g:ctrlspace_show_unnamed = 1 then unnamed buffers will be shown on the list all the time. However, if you set this value to 2, unnamed buffers will be displayed only if they are modified or just visible on the screen. Of course you can hide unnamed buffers permanently by setting g:ctrlspace_show_unnamed = 0. Default value: 2.

`g:ctrlspace_set_default_mapping`

Turns on the default mapping. If you turn this option off (0) you will have to provide your own mapping to the CtrlSpace yourself. Default value: 1.

`g:ctrlspace_default_mapping_key`

By default, Vim-CtrlSpace maps itself to Ctrl + Space. If you want to change the default mapping provide it here as a string with valid Vim keystroke notation. Default value: "<C-Space>".

`g:ctrlspace_cyclic_list`

Determines if the list should be cyclic or not. The cyclic list means you will jump to the last item if you continue to move up beyond the first one and vice-versa. You will jump to the first one if you continue to move down after you reach the bottom of the list. Default value: 1.

`g:ctrlspace_max_jumps`

The size of jumps history. Each tab has its own jumps list (plus there is an extra one for all buffers). Those lists are accessible via p and n keys. Their size will not exceed a number given in that option. That means, the entries older than n last jumps will be removed. Default value: 100.

`g:ctrlspace_max_searches`

The size of search history. Each tab has its own search history available through Ctrl + p and Ctrl + n. The search list size will not exceed the number given here. That means, the entries older than n last searches will be removed. Default value: 100.

`g:ctrlspace_default_sort_order`

The default sort order. 0 turns off sorting, 1 - the default sorting is chronological, 2 - alphanumeric. Default value: 2.

`g:ctrlspace_use_ruby_bindings`

If set to 1, the plugin will try to use your compiled in Ruby bindings to increase the speed of the plugin (e.g. while fuzzy search, since regex operations are much faster in Ruby than in VimScript). Default value: 1.

To see if you have Ruby bindings enabled you can use the command :version and see if there is a +ruby entry. Or just try the following one: :ruby puts RUBY_VERSION - you should get the Ruby version or just an error.

`g:ctrlspace_use_tabline`

Should Vim-CtrlSpace change your default tabline to its own? Default value: 1.

`g:ctrlspace_use_mouse_and_arrows`

Should the plugin use mouse, arrows and Home, End, PageUp, PageDown keys. Disables the Esc key if turned on. Default value: 0.

`g:ctrlspace_workspace_file`

This entry provides an array of strings with default names of workspaces file. If a name is preceded with a directory, and that directory is found in the project root, that entry will be used. Otherwise that would be the last one. In that way you can hide the workspaces file, for example, in the repository directory. Default value:

[".git/cs_workspaces", ".svn/cs_workspaces", ".hg/cs_workspaces", 
\ ".bzr/cs_workspaces", "CVS/cs_workspaces", ".cs_workspaces"]

`g:ctrlspace_save_workspace_on_exit`

Saves the active workspace (if present) on Vim quit. If this option is set, the Vim quit (Q) action from the plugin modes does not check for workspace changes. Default value: 0.

`g:ctrlspace_load_last_workspace_on_start`

Loads the last active workspace (if found) on Vim startup. Default value: 0.

`g:ctrlspace_cache_dir`

A directory for the Vim-CtrlSpace cache file (.cs_cache). By default your $HOME directory will be used.

`g:ctrlspace_project_root_markers`

An array of directory names which presence indicates the project root. If no marker is found, you will be asked to confirm the project root basing on the current working directory. Make this array empty to disable this functionality. Default value: [".git", ".hg", ".svn", ".bzr", "_darcs", "CVS"].

`g:ctrlspace_unicode_font`

Set to 1 if you want to use Unicode symbols, or 0 otherwise. Default value: 1.

`g:ctrlspace_symbols`

Enables you to provide your own symbols. It's useful if for example your font doesn't contain enough symbols or the glyphs are poorly rendered. Default value:

if g:ctrlspace_unicode_font
  let g:ctrlspace_symbols = {
        \ "cs"      : "▢",
        \ "tab"     : "⊙",
        \ "all"     : "∷",
        \ "add"     : "○",
        \ "load"    : "⋮ → ∙",
        \ "save"    : "∙ → ⋮",
        \ "ord"     : "₁²₃",
        \ "abc"     : "авс",
        \ "prv"     : "⌕",
        \ "s_left"  : "›",
        \ "s_right" : "‹"
        \ }
else
  let g:ctrlspace_symbols = {
        \ "cs"      : "CS",
        \ "tab"     : "TAB",
        \ "all"     : "ALL",
        \ "add"     : "ADD",
        \ "load"    : "LOAD",
        \ "save"    : "SAVE",
        \ "ord"     : "123",
        \ "abc"     : "ABC",
        \ "prv"     : "*",
        \ "s_left"  : "[",
        \ "s_right" : "]"
        \ }
endif

Of course, you don't have to mind the g:ctrlspace_unicode_font settings anymore. Just provide one array here.

`g:ctrlspace_ignored_files`

The expression used to ignore some files during file collecting. It is used in addition to the wildignore option in Vim (see :help wildignore). Default value: '\v(tmp|temp)[\/]'

`g:ctrlspace_show_key_info`

Should the key info help (toggled by ?) be visible (1) by default or not (0). Default value: 0.

`g:ctrlspace_show_tab_info`

Should the tab info be visible (1) or not (0). Default value: !&showtabline. That means that it will be enabled by default if you turn off the default tabline.

`g:ctrlspace_search_timing`

Allows you to adjust search smoothness. Contains an array of two integer values. If the size of the list is lower than the first value, that value will be used for search delay. Similarly, if the size of the list is greater than the second value, then that value will be used for search delay. In all other cases the delay will equal the list size. That way the plugin ensures smooth search input behavior. Default value: [50, 500]

Colors

The plugin allows you to define its colors entirely. By default it comes with pure black and white color set. You are supposed to tweak its colors on your own (in the .vimrc file). This can be done as shown below:

hi CtrlSpaceSelected term=reverse ctermfg=187  ctermbg=23  cterm=bold
hi CtrlSpaceNormal   term=NONE    ctermfg=244  ctermbg=232 cterm=NONE
hi CtrlSpaceFound    ctermfg=220  ctermbg=NONE cterm=bold

The colors defined above can be seen in the demo movie. They fit well the Seoul256 color scheme. Another useful example can be found here:

hi CtrlSpaceSelected term=reverse ctermfg=white ctermbg=black cterm=bold
hi CtrlSpaceNormal   term=NONE    ctermfg=black ctermbg=228   cterm=NONE
hi CtrlSpaceFound    ctermfg=125  ctermbg=NONE  cterm=bold

If you use a console Vim that chart might be helpful.

API

Commands

At the moment Vim-CtrlSpace provides you 4 commands: :CtrlSpace and :CtrlSpaceTabLabel, :CtrlSpaceSaveWorkspace, and :CtrlSpaceLoadWorkspace.

`:CtrlSpace`

Shows the plugin window. It is meant to be used in custom mappings or more sophisticated plugin integration.

`:CtrlSpaceTabLabel`

Allows you to define a custom mapping (outside Vim-CtrlSpace) to change (or add/remove) a custom tab name.

`:CtrlSpaceClearTabLabel`

Removes a custom tab label.

`:CtrlSpaceSaveWorkspace [my workspace]`

Saves the workspace with the given name. If no name is given then it saves the active workspace (if present).

`:CtrlSpaceLoadWorkspace [my workspace]`

Loads the workspace with the given name. It has also a banged version (:CtrlSpaceLoadWorkspace! my workspace) which performs appending instead of loading. If no name is give then it loads (or appends) the active workspace (if present).

Functions

Vim-CtrlSpace provides you a couple of functions defined in the common ctrlspace namespace. They can be used for custom status line integration, tabline integration, or just for more advanced interactions with other plugins.

`ctrlspace#bufferlist(tabnr)`

Returns a directory of buffer number and name pairs for given tab. This is the content of the internal buffer list belonging to the specified tab.

`ctrlspace#statusline_key_info_segment(...)`

Returns the info about available keys for the current plugin mode (toggled by ?). It can take an optional separator. It can be useful for a custom status line integration (i.e. in plugins like LightLine)

`ctrlspace#statusline_info_segment(...)`

Returns the info about the mode of the plugin. It can take an optional separator. It can be useful for a custom status line integration (i.e. in plugins like LightLine)

`ctrlspace#statusline_tab_info_segment(...)`

Returns the info about the current tab (tab number, label, etc.). It is useful if you don't use the custom tabline string (or perhaps you have set showtabline to 0 (see :help showtabline for more info)).

`ctrlspace#tabline()`

Provides the custom tabline string.

`ctrlspace#guitablabel()`

Provides the custom label for GVim's tabs.

Authors and License

Copyright © 2013-2014 Szymon Wrozynski and Contributors. Licensed under MIT License conditions. Vim-CtrlSpace is based on Robert Lillack plugin VIM bufferlist © 2005 Robert Lillack. Moreover some concepts of and inspiration has been taken from Vim-Tabber by Jim Steward and Tabline by Matthew Kitt.

Vim-CtrlSpace

TL;DR

Demo

About

The Story

Vim-CtrlSpace Idea

Installation

Usage

Status Line

Status Line Symbols

Tabline

Tab Management

Project Root

Main Modes

Simplified Key Diagram

Single Tab Mode

Keys Reference

All Tabs Mode

Add Mode

Keys Reference

Workspace Mode

Keys Reference

Tablist Mode

Keys Reference

Auxiliary Modes

Preview Mode

Search Mode

Keys Reference (entering phase)

Nop Mode

Nop (Search entering phase)

Nop (outside the entering phase)

Configuration

g:ctrlspace_height

g:ctrlspace_max_height

g:ctrlspace_show_unnamed

g:ctrlspace_set_default_mapping

g:ctrlspace_default_mapping_key

g:ctrlspace_cyclic_list

g:ctrlspace_max_jumps

g:ctrlspace_max_searches

g:ctrlspace_default_sort_order

g:ctrlspace_use_ruby_bindings

g:ctrlspace_use_tabline

g:ctrlspace_use_mouse_and_arrows

g:ctrlspace_workspace_file

g:ctrlspace_save_workspace_on_exit

g:ctrlspace_load_last_workspace_on_start

g:ctrlspace_cache_dir

g:ctrlspace_project_root_markers

g:ctrlspace_unicode_font

g:ctrlspace_symbols

g:ctrlspace_ignored_files

g:ctrlspace_show_key_info

g:ctrlspace_show_tab_info

g:ctrlspace_search_timing

Colors

API

Commands

:CtrlSpace

:CtrlSpaceTabLabel

:CtrlSpaceClearTabLabel

:CtrlSpaceSaveWorkspace [my workspace]

:CtrlSpaceLoadWorkspace [my workspace]

Functions

ctrlspace#bufferlist(tabnr)

ctrlspace#statusline_key_info_segment(...)

ctrlspace#statusline_info_segment(...)

ctrlspace#statusline_tab_info_segment(...)

ctrlspace#tabline()

ctrlspace#guitablabel()

Authors and License

About

Languages

`g:ctrlspace_height`

`g:ctrlspace_max_height`

`g:ctrlspace_show_unnamed`

`g:ctrlspace_set_default_mapping`

`g:ctrlspace_default_mapping_key`

`g:ctrlspace_cyclic_list`

`g:ctrlspace_max_jumps`

`g:ctrlspace_max_searches`

`g:ctrlspace_default_sort_order`

`g:ctrlspace_use_ruby_bindings`

`g:ctrlspace_use_tabline`

`g:ctrlspace_use_mouse_and_arrows`

`g:ctrlspace_workspace_file`

`g:ctrlspace_save_workspace_on_exit`

`g:ctrlspace_load_last_workspace_on_start`

`g:ctrlspace_cache_dir`

`g:ctrlspace_project_root_markers`

`g:ctrlspace_unicode_font`

`g:ctrlspace_symbols`

`g:ctrlspace_ignored_files`

`g:ctrlspace_show_key_info`

`g:ctrlspace_show_tab_info`

`g:ctrlspace_search_timing`

`:CtrlSpace`

`:CtrlSpaceTabLabel`

`:CtrlSpaceClearTabLabel`

`:CtrlSpaceSaveWorkspace [my workspace]`

`:CtrlSpaceLoadWorkspace [my workspace]`

`ctrlspace#bufferlist(tabnr)`

`ctrlspace#statusline_key_info_segment(...)`

`ctrlspace#statusline_info_segment(...)`

`ctrlspace#statusline_tab_info_segment(...)`

`ctrlspace#tabline()`

`ctrlspace#guitablabel()`