vim9-winswap

• 1. Demonstrations
  • 1.1. Demo 1: Swapping windows
  • 1.2. Demo 2: Putting a window
  • 1.3. Demo 3: Using :Winswap to swap windows
  • 1.4. Demo 4: Swapping windows between tabs
• 2. How to swap windows
• 3. How to put (clone) a window
• 4. How to swap windows by window number
• 5. Mappings
  • 5.1. Using g:winswap_opt_maps
  • 5.2. <Plug> mappings and customising your mappings
• 6. Installation
  • 6.1. Using Vim’s package management
  • 6.2. vim-plug
• 7. BSD Zero Clause License

This Vim9 script plugin enables you to swap or clone Vim windows easily. As a Vim9 script plugin, it works with Vim exclusively, and requires Vim version 9 (though from 8.2.4883 should work too).

Vim’s native window CTRL-W commands, like CTRL-W r, CTRL-W x, and CTRL-W T, work well in many scenarios. However, there are limitations. For example, CTRL-W r, “only works within the row or column of windows that the current window is in”. Also, there is no ability to move windows to another existing tab.

vim9-winswap lets you:

1. Swap a chosen window with any other, including a window in another existing tab, or

2. Put (clone) a chosen window into any other window, leaving the “yanked” window as-is, or

3. Use :Winswap to swap two chosen windows (within the same tab).

In all instances:

• Window-local options are carried across to the moved or cloned window. That is, options like list, colorcolumn, and spell, which are exclusively window-local.

• The state of the marked/“yanked” window is cleared following a swap or put.

ℹ️

The plugin vim-windowswap is a legacy vimscript plugin, which provides some similar functionality for swapping windows. Its “swap” key mapping, <Leader>ww, has been used in this plugin’s optional mappings. There are improvements in vim9-winswap, too; e.g., ensuring the window-local settings are carried across.

1. Demonstrations

1.1. Demo 1: Swapping windows

1.2. Demo 2: Putting a window

1.3. Demo 3: Using :Winswap to swap windows

1.4. Demo 4: Swapping windows between tabs

2. How to swap windows

As shown in Demo 1 and Demo 4:

1. Navigate to the first window you want to swap.

2. <Leader>ww to mark the first window and remember its settings.

3. Navigate to the second window you want to swap with the first.

4. <Leader>ww to remember the second window’s settings and swap the windows.

ℹ️	<Leader>ww is not fixed - you can choose whatever you want - but it is enabled if you used g:winswap_opt_maps = true in your (Vim9) .vimrc/_vimrc.

3. How to put (clone) a window

As shown in Demo 2:

1. Navigate to the window you want to put.

2. <Leader>ww to mark the window and remember its settings.

3. Navigate to the window you want to substitute.

4. <Leader>wp to substitute the window with the cloned window from point 1.

ℹ️	<Leader>wp is not fixed - you can choose whatever you want - but it is enabled if you used g:winswap_opt_maps = true in your (Vim9) .vimrc/_vimrc.

4. How to swap windows by window number

As shown in Demo 3, if you know the window numbers of the two windows you want to swap, you can use the :Winswap command:

:Winswap 4 2

This swaps windows 4 and 2. The command accepts any two valid window numbers (though only within the same tab).

ℹ️	For convenience, there is command abbreviation Ws, which expands to Winswap.

5. Mappings

5.1. Using g:winswap_opt_maps

If you are satisfied with using <Leader>ww and <Leader>wp, as explained in How to swap windows and How to put (clone) a window, all you need to do is include the following in your .vimrc/_vimrc:

g:winswap_opt_maps = true

5.2. <Plug> mappings and customising your mappings

There are only two inherent mappings, both of which only work in Normal mode. They are <Plug> mappings, so they should not conflict with anything:

• <Plug>(Winswap_ww)

  If there is no currently marked window, this marks it as the window that will either be swapped or put/cloned. If there already is a currently marked window, it swaps the two windows.

• <Plug>(Winswap_wp)

  Provided there is a currently marked window, this will put it (clone it to) where the current window is.

If you want to map either or both of the <Plug> mappings to keys of your own choosing, it is easy. For example:

nnoremap <C-W>2 <Plug>(Winswap_ww)
nnoremap <C-W>1 <Plug>(Winswap_wp)

Now <C-W>2 will do the same as what <Leader>ww would do and <C-W>1 will do the same as what <Leader>wp would do.

🔥	If you use sessions, mappings including <ScriptCmd>, which is what vim9-winswap uses, will be broken when a session is restored. This is a known issue, which, at the time of writing may be fixed in future. However, to avoid the issue, an autocmd and function may be added to your .vimrc/_vimrc.

6. Installation

6.1. Using Vim’s package management

From your terminal:

git clone https://github.com/kennypete/vim9-winswap ~/.vim/pack/plugins/start/vim9-winswap

Adjust this as necessary for Windows and/or for plugins, which can be whatever you want. Also, if you want manual control of plugin loading, use opt instead of start, then include packadd vim9-winswap in your .vimrc/_vimrc.

6.2. vim-plug

Add to your .vimrc/_vimrc, with your other plugins, Plug 'kennypete/vim9-winswap'.

7. BSD Zero Clause License

Copyright © 2025 Peter Kenny

Permission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted.

THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.