<!-- vim: set filetype=markdown: --> <!-- vim-markdown-toc GFM -->

• Introduction
  • What is it ?
  • What does it look like ?
    • History and meta-command
    • Frecency, dedicated buffers and layers
    • More screenshots & screencasts
  • File groups & categories
    • Why do you need three levels of grouping ?
    • A wheel that follows you
  • Features
  • History
  • Prerequisites
    • Software
    • Operating system
• Installation
  • Using vim-packager
  • Using minpac
  • Using vim-plug
  • Cloning the repo in a pack-start directory
• Documentation
  • Vim help
  • Wiki
  • In wheel menu
• Configuration
  • Wiki
  • Example
• Meta-command
• Bindings
  • Frequently used functions
• Examples
  • Display matching files in splits
  • More
• Warning

<!-- vim-markdown-toc -->

Introduction

What is it ?

Wheel is a :

• file group manager
• session manager (tabs & windows)
• navigation plugin
• refactoring tool

for Vim and Neovim.

Our favorite editor has already plenty of nice navigation functions. Wheel enhances their interface by using :

• intuitive completion with multi-pattern support for prompting functions
• dedicated buffers, in which you can filter and select elements, besides using the full power of your editor
• a meta-command with subcommands, actions and completion
• edit modes, that allow you to reflect your changes in a dedicated buffer to the original file(s)

With these tools, any line in any file is only a few keys away.

All is written in lightweight, classical Vimscript. No dependency required.

What does it look like ?

History and meta-command

Frecency, dedicated buffers and layers

More screenshots & screencasts

See the wheel-multimedia repository.

File groups & categories

Wheel let you organize your files by creating as many file groups as you need, add the files you want to it and quickly navigate between :

• files of the same group
• file groups

Note that :

• a location contains a name, a filename, as well as a line & column number
• a file group, in fact a location group, is called a circle
• a set of file groups, or a category, is called a torus (a circle of circles)
• the list of toruses is called the wheel

Currently, there are more than a thousand files in my groups, and it runs like a breeze.

Why do you need three levels of grouping ?

At first glance, managing groups with circles in a torus seems to be sufficient. But with time, the torus grows big, and a third level helps you to organize your files by groups and categories:

• the wheel contains all the toruses
• each torus contains a category of files, e.g.:
  • configuration, development, publication
• each circle contains a project, e.g.:
  • kitty or vifm circles in configuration torus
  • shell or vimscript in development torus
  • tea or art in publication torus

You can also organize a torus in subprojects. For instance, in the wheel torus, I have the following groups :

• plugin/ dir files
• autoload/ dir files
• doc files
• wiki files
• test files

A wheel that follows you

Wheel is designed to follow your workflow : you only add the files you want, where you want. For instance, if you have a organize group with agenda & todo files, you can quickly alternate them, or display them in two windows. Then, if you suddenly got an idea to tune vim, you switch to the vim group with your favorites configuration files in it. Same process, to cycle, alternate or display the files. Over time, your groups will grow and adapt to your style.

Features

The group manager is the core, but it goes far beyond that : you need a quick navigation framework to travel in the wheel, and once it is there, it’s easy to add new functionalities.

• add
  • files from anywhere in the filesystem
  • a file in more than one group
  • file:line-1 and file:line-2 in the same group
• may be saved in wheel file (recommended)
• on demand loading of files
  • no slowdown of (neo)vim start
• easy navigation
  • switch to matching tab & window if available
  • next / previous location, circle or torus
  • single or multi-pattern completion in prompting functions
  • choose file, group or category in dedicated buffer
    • filter candidates
    • selection tools
    • preview
    • folds matching wheel tree structure
    • context menus
  • auto :lcd to project root of current file
  • history of wheel files
    • anywhere
    • in same group
    • in same category
  • signs displayed at wheel locations
• search files
  • using locate
  • using find
  • MRU files not found in wheel
  • opened buffers
  • visible buffers in tabs & windows
• search inside files
  • grep on group files
    • navigate
    • edit mode : edit and propagate changes by writing the dedicated buffer
  • outline
    • folds headers in group files (based on fold markers)
    • markdown headers
    • org mode headers
  • tags
  • markers
  • jumps & changes lists
• narrow
  • current file
  • all circle file with a pattern
• yank ring using TextYankPost event
  • paste before or after, linewise or characterwise
  • switch register ring
• reorganizing
  • wheel elements
  • tabs & windows
• undo list
  • diff between last & chosen state
• command output in buffer
  • :ex or !shell command
  • async shell command
  • result can be filtered, as usual
• dedicated buffers ring to save your searches
  • layer ring in each dedicated buffer
• batch operations
• autogroup files by extension or directory
• save tabs & windows in minimal session file
• display files
  • split levels : torus, circle, location
  • split
    • vertical, golden vertical
    • horizontal, golden horizontal
    • main left, golden left
    • main top, golden top
    • grid
  • mix of above
    • circles on tabs, locations on split
    • toruses on tabs, circles on split

History

This project is inspired by :

• torus, a file group plugin for Emacs, itself inspired by MTorus

• ctrlspace, a workspace plugin for Vim

• unite, a search plugin for arbitrary sources

• quickfix-reflector, for the grep edit mode

• NrrwRgn, for the narrow dedicated buffers

• YankRing, whose name is self-explanatory

Prerequisites

Software

• vim >= 8.2
• neovim >= 0.6

Basically, it assumes the existence of :map-cmd and #{...} syntax for dictionaries.

If your distribution uses an older version, you can resort to appimages :

• vim appimage
• neovim appimage

These are fast evolving pieces of software, it's worth upgrading anyway.

Operating system

Some outer rim functions assume a Unix-like OS, like Linux or BSD :

• async functions
• external commands, like locate
• mirror the wheel structure in a filesystem tree

Most of the plugin should work out of the box on other OSes, however. If you encounter some problem, please let me know.

Installation

Using vim-packager

Simply add this line after packager#init() to your initialisation file :

call packager#add('chimay/wheel', { 'type' : 'start' })

and run :PackagerInstall (see the vim-packager readme).

Using minpac

Simply add this line after minpac#init() to your initialisation file :

call minpac#add('chimay/wheel', { 'type' : 'start' })

and run :PackUpdate (see the minpac readme).

Using vim-plug

The syntax should be similar with other git oriented plugin managers :

Plug 'chimay/wheel'

and run :PlugInstall to install.

Cloning the repo in a pack-start directory

You can clone the repository somewhere in your runtime-search-path. You can get a minimal version by asking a shallow clone (depth 1) and filtering out the screenshots blobs :

mkdir -p ~/.local/share/nvim/site/pack/foo/start
cd ~/.local/share/nvim/site/pack/foo/start
git clone --depth 1 --filter=blob:none https://github.com/chimay/wheel

If you install or update with git, don't forget to run :

:helptags doc

to be able to use the inline help.

Documentation

Vim help

Your guide on the wheel tracks :

:help wheel.txt

Wiki

A wheel wiki is also available.

It is recommended to read at least the step-by-step and workflow pages, either in the wiki or in the wheel.txt file.

In wheel menu

In the help submenu of the main menu (default map : <M-w><M-m>), you have access to :