You are viewing the documentation for the develop branch. The documentation for the release version is here .

Table of Contents

spacemacs-layouts layer

Table of ContentsClose

1. Description

This layer adds support for distinct layouts/workspaces to Spacemacs.

Layouts provide an easy way to group buffers for a project or any arbitrary buffer grouping you wish. Layouts also restrict actions to the buffers in the current layout.

1.1. Features:

  • Support for distinct layouts via eyebrowse
  • Integration with helm and ivy to search for buffers within layouts

2. Install

The spacemacs-layouts layer is included by default in the Spacemacs distribution.

To set configuration layer variables, add spacemacs-layouts to the existing dotspacemacs-configuration-layers list in your ~/.spacemacs file.

2.1. Restrict functions to the current layout's buffers

Besides helm-mini and ivy-switch-buffer that are aware of a layout's buffers. This layer also provides a spacemacs-layouts-restricted-functions variable that holds a list of functions that will be restricted to the current layout's buffers.

Default value of spacemacs-layouts-restricted-functions is:


The list can be edited in the dotspacemacs-configuration-layers variable near the top of .spacemacs like this:

(spacemacs-layouts :variables

Note that spacemacs-layouts-restricted-functions can only be changed in the dotspacemacs-configuration-layers variable. They can't be edited during the current Emacs session. A restart is required.

2.2. Restrict SPC-TAB to the current layout's buffers

When the spacemacs-layouts-restrict-spc-tab variable is set to t, then SPC-TAB (spacemacs/alternate-buffer) will be restricted to only switch between the current layout's buffers.

Default value of spacemacs-layouts-restrict-spc-tab is nil.

It can be enabled in the dotspacemacs-configuration-layers variable near the top of .spacemacs like this:

(spacemacs-layouts :variables
                   spacemacs-layouts-restrict-spc-tab t)

Note that spacemacs-layouts-restrict-spc-tab also can be toggle on the fly by evaluating it like this:

(setq spacemacs-layouts-restrict-spc-tab t)

2.3. Kill buffers when killing current layout

SPC l x kills the current layout and the buffers stay open by default. persp-autokill-buffer-on-remove controls what happens when a layout is killed nil keeps all buffers kill-weak kills a buffer if it is not in any other layout except default t will kill all buffers in the current layout

(spacemacs-layouts :variables
                   persp-autokill-buffer-on-remove 'kill-weak)

If this variable is not set, then SPC l x kills the current layout, the buffers remain open and listed in the default layout.

3. Usage

Layout 1 is the default layout and has global scope, so SPC b b lists all open buffers. All other layouts only show the buffers associated with that layout.

SPC l to select from the current layouts by number or navigate with n / p ? will display the help menu.

SPC l l to select or create a layout by typing the layout name.

SPC l d to close the current layout, SPC l x to kill the current layout.

See key bindings for more layout commands.

4. Key bindings

Key binding Description
SPC l ? toggle hint in layouts transient state
SPC l 1 switch to layout 1
SPC l 2 switch to layout 2
SPC l 3 switch to layout 3
SPC l 4 switch to layout 4
SPC l 5 switch to layout 5
SPC l 6 switch to layout 6
SPC l 7 switch to layout 7
SPC l 8 switch to layout 8
SPC l 9 switch to layout 9
SPC l 0 switch to layout 0
SPC l C-1 switch to layout 11
SPC l C-2 switch to layout 12
SPC l C-3 switch to layout 13
SPC l C-4 switch to layout 14
SPC l C-5 switch to layout 15
SPC l C-6 switch to layout 16
SPC l C-7 switch to layout 17
SPC l C-8 switch to layout 18
SPC l C-9 switch to layout 19
SPC l C-0 switch to layout 20
SPC l TAB jump to last layout
SPC l RET exit layout transient state
SPC l C-h previous layout
SPC l C-l next layout
SPC l < move current layout left
SPC l > move current layout right
SPC l a add buffer to layout
SPC l A import buffers
SPC l b list buffers open in layout
SPC l d close current layout (keeps buffers open)
SPC l e switch to/create layout at position
SPC l D close-other layout
SPC l h Switch to default layout
SPC l L Load saved layouts from a file
SPC l l select or create a layout by name
SPC l n next layout
SPC l N previous layout
SPC l o select custom layout
SPC l p persp-prev
SPC l r remove buffer from layout
SPC l R rename layout
SPC l s save current layouts to file
SPC l S save current layouts to file by names
SPC l t temporarily display buffer
SPC l w workspaces transient state
SPC l x kill current layout
SPC l X kill other layout

Author: root

Created: 2021-09-11 Sat 23:13